Skip to end of metadata
Go to start of metadata

Introduction

This page describes how to create and configure an OData Service API, access existing OData APIs, and edit the configuration settings of existing OData APIs within Jitterbit Harmony API Manager

OData is a flexible, REST-based protocol that is used to query multiple unique data sources and transform the data into a single, standard data model to be consumed by other applications and services. A common use case for an OData Service API is retrieving data from SAP and multiple databases, such as Oracle, MySQL, and SQL Server, to be consumed by Salesforce Connect.

Jitterbit Harmony currently supports OData 2.0 for Oracle, MySQL, Microsoft SQL Server, and PostgreSQL. In general, a standard JDBC driver can be used with Jitterbit Harmony. However, you would need to perform validation and testing to confirm that a driver other than these will work for this purpose. For additional information about the OData protocol, see OData 2.0.

TIP: 

Getting Started

API Manager is accessed from the Harmony Portal. The credentials you use depend on whether or not your organization and account is configured to use Single Sign-On (SSO). Once you are logged into the Harmony Portal, you can access the My APIs landing page:

  • From the Harmony Portal landing page, by selecting the API Manager card.
  • From any page within the Harmony Portal, by using the hamburger menu in the top left corner to select API Manager > My APIs
  • From any page within API Manager, by clicking the logo or the words API Manager in the top left next to the menu.

View this video to preview the steps to create an OData Service API:

Creating a New OData Service API

When you access API Manager, if no APIs exist in the selected organization, this page will be blank. Click New API in the upper right side of the page to get started:

Selecting New API opens the Publish New API page. 

The process of creating and publishing a new API consists of four steps. Each step is a separate page with the step number highlighted at the top of the page:

You can navigate back to a previous step by selecting the step numbers on top of the page, or you can select Cancel at the bottom of each page to stop the process at any time.

On each page of Publish New API:

  • Save Changes: This option is available only after opening an existing API to edit, and it is activated only after changes are made to the page. Click Save Changes to save the changes you made in this page. A popup window displays a message giving you the option to Save Changes or Discard Changes. Click Save Changes to save the changes you made, close the popup, and return to the Summary & Confirmation page. Click the Discard Changes link to delete the changes you made to this page, close the popup, and return to the Summary & Confirmation page.
  • Discard Changes: This option is available only after opening an existing API and only after you have made changes to the page. Click the Discard Changes link if you do not want to save the changes you made to this page. A popup windows displays a message giving you the option to Save Changes or Discard Changes. Click Discard Changes to delete the changes you made to this page, close the popup, and return to the Summary & Confirmation page. Click the Save Changes link to save the changes you made, close the popup, and return to the Summary & Confirmation page. 

Step 1: Settings

  • API Name: Enter a name for the ODATA Service API. The name should be short and describe the functionality of the API. The API name is important for internal identification and is also used in the service root (the public name) of the API. The name automatically becomes part of the API URL.
  • Environment: Click in the Environment field to display the dropdown list.  Select in the list the Environment your OData Service API project resides in.
  • Service Root: The Service Root field is automatically populated with the API Name entered above and is translated into camel case. If a different service root is preferred, enter the name in the Service Root field. 
    • Jitterbit uses camel case in the service root. The API Name entered as "SAP Customer Data" automatically populates the Service Root field as "sapCustomerData" using camel case. Additional information regarding camel case is available on Lodash.com
    • A space between words and any underscore "_" entered between words in the API Name is ignored in the service root.
    • The underscore "_" character may be entered manually within the Service Root field and is then included in the final API URL.
    • A manually entered space is not allowed in the service root or the final API URL.
    • All special characters, other than the underscore, are not allowed in the service root or the final API URL.

  • Version#: Define a version method for this API and enter the version in the Version# field. While this is not required, it is highly recommended. The V1, V2, etc. naming convention is often utilized. You can use any alphanumeric character for the version, including a date. Special characters are not allowed in the version, except for a period or hyphen. A maximum of 48 characters is allowed in the version field. The version will also become part of the URL to help you and your customers distinguish your various APIs in the future.
  • Description: Enter a short description of the OData Service API in the Description field. This description will appear in the My APIs index and can help project collaborators identify an API.
  • Scroll down to the TIMEOUT field:

  • TIMEOUT: Enter the number of seconds before the API will time out. The default is 30 seconds. The maximum is 180 seconds.
  • SSL Only: SSL communication security is enabled by default and is strongly recommended. To disable SSL only, click the checkbox to clear it. 
  • Enable CORS: Click the checkbox to enable CORS. A warning note displays. Review the warning (for additional information, see https://www.w3.org/TR/cors/). Select Continue to enable CORS or Cancel to disable CORS and close the popup window.

  • Enable Verbose Logging: Click the checkbox to enable verbose logging. Verbose logging for APIs allows the user to decide whether each API log should contain request and response data. This functionality helps monitor incoming and outgoing data as well as facilitate debugging API issues. 
    • This option can be enabled or disabled at any time by hovering over the API card in the My APIs Index page and selecting View/Edit on the back side of the card. 
    • When this option is selected, a popup window displays. Select Continue to enable verbose logging, select Cancel to disable verbose logging and close the window.
  • Scroll down to the Enable Debug Mode Until field:

  • Enable Debug Mode Until: Debug logging is disabled by default. Click the checkbox to enable debug logging. 
    • A popup message describes debug mode processing and the consequences of running in debug mode for long periods of time.  
    • Select Continue to enable debug mode or Cancel to disable debug mode and close the popup window.  
    • Once enabled, debug logging is set to run until exactly one hour from the date and time it is enabled.  These are the steps to change the default date and time:
      • Click within the date field to display a calendar to set a longer period to run in debug mode. Two weeks is the maximum time allowed to enable running in debug mode. Select the day in the calendar.

      • Click in the time field. Click the up and down arrows to set the hour and minutes. Click Set to accept the time.

      • Click Cancel to close the popup without making changes.
    • Debug logging can be turned on at any time by hovering over the API card in the My APIs Index page and selecting View/Edit on the back side of the card. 
  • Next: Select Next to save the information entered in step 1 and continue to step 2.
  • Cancel: Selecting Cancel at the bottom of the page or selecting the close icon  in the top right corner of the page will close the page without saving the information already entered in step 1.
  • Save Changes and Discard Changes: See instructions above.

Step 2: Select Service Type and Assign Jitterbit Entities

  • Service URL: The Service URL displays at the top of the page in steps 2 through 4. As shown above, the service URL is https://JitterbitTRIAL######.jitterbit.net/Prod/v1.0/sapCustomerData. The service URL is created from the fields populated in step 1
    • https://JitterbitTrial######.jitterbit.net: This is the base API URL for your org. The base URL is composed of your organization's org number, assigned at the time the subscription license is purchased (format JitterbitTrial#####) and your Harmony region (APAC, EMEA, or NA):

      RegionRegion Base URL

      APAC

      JitterbitTrial#####.Jitterbit.cc
      EMEAJitterbitTrial#####.Jitterbit.eu
      NAJitterbitTrial#####.Jitterbit.net
    • /Prod: This is determined by the selection in the Environment field of step 1 and is the value in the URL prefix field of an environment. The URL prefix field, limited to a maximum of 48 characters, is populated at the time an environment is created. Detailed instructions for setting up environments are available within our existing Management Console documentation on the Environments page.
    • /v1.0: The value entered in the Version# field of step 1.
    • /sapCustomerData: The value in the Service Root field of step 1. In the example, we allowed the value entered in the API Name field to autofill the Service Root field using camel case. 
  • Service Type: To help in determining the correct service type, hover over each information icon  to view a description of Custom API and OData Service. Select the radio button for the appropriate Service Type for your API. The project and API Entity operation used in this example are designed for an OData Service API. 
  • Scroll down to Assign Jitterbit Entities

  • Entity (Project): Click on Entity (Project) to display the list of the Entities and associated projects available in the environment selected in step 1. Select your Jitterbit Entity from the list. 

  • Operation: Click on Operation to display the list of the API Entity operations available from within the Entity you selected. Select the API Entity Operation from the list. 
  • Method: Click on Method to display the list of method types available (Get, Post, Put, Delete, Patch, Merge). Select an appropriate Method type from the list. 
  • Response Type: Click on Response Type to display the list of response types (Final Target, System Variable, No Response). Select an appropriate Response Type from the list.

    TIP: To help determine the correct response type, select each of the three types individually and hover over the information icon  to display a description, requirements, and consequences of selecting a type.

  • Assign Entity: This button is activated once the Entity, API Entity operation, method, and response type are selected. Click Assign Entity
    • At least one API Entity operation must be assigned in order to continue through the remaining steps to create an OData Service API.  
    • The assigned selections display in the table at the bottom of the page as shown here:

  • Repeat step 2 to assign additional API Entity operations within the same Entity to the API. Each operation within an entity can be assigned only once to the API and assigned to only one method. 
  • Repeat step 2, or to assign multiple operations and methods to the API. Once completed, all assigned operations and associated methods display in the table.
  • To delete an operation, hover over the row and select the delete icon .
  • To make changes to an assigned operation, click on the row in the table:


    • The row is now highlighted, and the Projects, Operation, Method, and Response Type fields are now populated with the selected operation information.
    • Make the necessary changes in the Projects, Operation, Method, and Response Type fields.
    • Save Entity: Select Save Entity (above the table) to save the changes to the selected operation and remain on the page.
    • Cancel: Select Cancel (above the table) to cancel the changes entered for the selected service and remain on the page.
  • Next: Select Next to save the information entered in step 2 and continue to step 3.
  • Cancel: Selecting Cancel at the bottom of the page or selecting the close icon  in the top right corner of the page, will close the page without saving the information entered in step 1 and step 2.
  • Save Changes and Discard Changes: See instructions above.

Step 3: Assign Security Profiles

There are three types of authentication available in API Manager: Anonymous, Basic, and OAuth 2.0. OAuth 2.0 is currently limited to Google, Salesforce, or Okta as the identity provider (IdP). See Harmony API Security and Security Profiles for additional information.

  • Select: Click on Select to display a list of existing security profiles. Select an appropriate Profile from the list.

  • Create New Profile: If an existing profile is not appropriate, click on the Create New Profile link to open the Security Profiles page and create a new profile (see Security Profile Creation and Configuration). When you save the new profile, you are returned to step 3 to assign the new profile to the new API you are creating.

  • Assign Profile: This button is enabled once a security profile is selected. Click Assign Profile. The profile assignment displays in the table at the bottom of the page:

  • Repeat step 3 to assign multiple security profiles to the API. Once completed, all assigned profiles display in the table. Select the delete icon  to the right if any of the settings are incorrect and repeat step 2 with the correct information. See Harmony API Security for additional information about assigning multiple profiles to an API.
  • Next: Select Next to continue to step 4.
  • Cancel: Selecting Cancel at the bottom of the page or selecting the close icon  in the top right corner of the page, will close the page without saving the information entered in step 1 through step 3.
  • Skip this Step: If a security profile has not been selected and assigned, selecting Skip this Step will continue to step 4 without assigning any security profile to the API. If the API is published prior to assigning a security profile, it is automatically anonymous and publicly accessible by default at the time it is published. 
  • Save Changes and Discard Changes: See instructions above.

Step 4: Summary & Confirmation

The Summary & Confirmation page displays all of the settings and selections made in the previous steps, allowing you to review, confirm, and edit the information prior to publishing the API. Each section of this page corresponds to a previous step:

  •  Settings: Along the top of the page is a summary of the Settings information entered in step 1, including the API name, environment, and description.
    • The Time Out, SSL Only, CORS, and Verbose Logging options are enabled if they display a check mark  to the left. Each option that displays an  to the left is disabled.
    • Enable Debug Mode Until: An orange checkmark displays to the left of the date and time fields if debug mode is enabled. The checkbox, date, and time are blank if debug mode is disabled. 
      • You can enable debug mode within this page by clicking the checkbox. The date and time will default to exactly one hour after you enable debug mode. 
      • A popup message describes debug mode processing and the consequences of running in debug mode for long periods of time.
      • Select Continue to enable debug mode or Cancel to disable debug mode and close the window.
      • Click in the date field to select a different date in the calendar. Click in the time field to select a different time.
    • Selecting the edit icon  to the right of the section returns you to the step 1 page for editing. 
  • Operations: The Operations section displays the information entered in step 2 including the Entities, projects, operations, methods, and response types assigned to the API.
    • Selecting the edit icon  to the right of the section returns you to the step 2 page for editing. 
  • Security Profiles: This section displays the information entered in step 3 including the profile name and authentication type for each security profile assigned to the API. 
    • Selecting the edit icon  to the right of the section returns you to the step 3 page for editing.
  • Clone: This option is available only after opening an existing API to edit. This creates an exact copy of the existing draft or published API, except for the API Name, Service Root, and Version fields. The phrase "Copy of" is appended to the beginning of the text in the API Name and Service Root fields. The text "-2" is appended to the end of the existing version. The cloned API is immediately opened in a new Summary & Confirmation window. You can rename the API, edit selected information, and then Save & Publish as a new API. You can change the version of the existing API and then Save As Draft until you are ready to publish the new version.
  • Export: This automatically exports the selected API to a file named apis-export.apk in your Downloads folder. This file can then be imported into a different environment or organization.
  • Delete: Click Delete to permanently delete the API from the organization and close the confirmation page. A popup message will ask you to confirm you want to delete the API.
    • If the API was published at the time of deletion, the API is removed from the My APIs page. It is also removed from the number of APIs used against your subscription limit. 
    • If the API was previously saved as a draft, the API is removed from the My APIs page. The number of APIs used against your subscription limit does not change as the API was not accessible while in draft status.
    • Select Continue to completely delete the API. Select Cancel if you want to close the popup window and return to the Summary & Confirmation page.

  • Save As Draft: Click this button to save the information entered or changed in step 1 through step 3 as a draft version.
    • If the API was previously published, the API displays on the My APIs page in "Published w/Draft" status. The published version of the API is still accessible and remains included in the number of APIs used against your subscription limit. The draft version of the API is not accessible and does not increase the number of APIs used against your subscription limit. 
    • If the API is new, or the API was previously saved as a draft, the API displays on the My APIs page in Draft status. The API is not accessible and is not added to the number of APIs used against your subscription limit.
    • You can return at any time to edit the draft API (see My APIs).
  • Save & Publish: Click this button to publish the API. The API is live and accessible within 5 minutes when accessed with the assigned profiles and authentication methods.
    • If the API was previously published, or was previously in "Published w/Draft" status, the API displays on the My APIs page as Published. The new published version of the API overwrites the previous published version. There still is only one version that is accessible. It does not increase the number of APIs used against the subscription limit. 
    • If the API is new, or the API was previously saved as a draft, the API displays on the My APIs page as Published. The API is now accessible and increases the number of APIs used against the subscription limit.
    • After selecting Save & Publish, a popup message displays indicating the OData Service API is live and accessible based on the assigned security profiles and ready to be consumed by other applications and services:


      • Copy URL: Click this link to copy the API URL to your clipboard. Paste the URL into a browser and press enter to test the API. For this example, the operation responds with XML output: 


      • Generate OpenAPI Document: NOTE: You cannot generate OpenAPI documentation for an OData Service API. This button will be removed in a future version of API Manager.
      • Dismiss: Click this link to close the popup window.
  • Cancel: Selecting Cancel will close the page without saving the information entered in any of these steps.

Salesforce Connect

To use the OData Service API with Salesforce Connect, continue with Setting Up Salesforce Connect to Consume an OData Service API.

On This Page



Last updated:  Jul 30, 2020


  • No labels