Skip to end of metadata
Go to start of metadata

Introduction

An API Request activity receives data from an API endpoint and is intended to be used a source to provide data to an operation. An API Response activity returns data to an API endpoint and is intended to be used as a target to consume data in an operation. Jitterbit Custom APIs are configured through API Manager.

The API Request or Response activities can be configured using a JSON, XML, CSV, or XSD schema. If instead you want to interact with an API connection using a WSDL schema, use an API SOAP Request or Response activity.

Using the preconfigured API connection, you can configure any number of API activities associated with an API endpoint.

Creating an API Activity

From the design canvas, open the Connectivity tab of the design component palette:

Use the Show dropdown to filter on Endpoints, and then click the preconfigured API connection block to display activities that are available to be used with an API connection:

To create an activity that can be configured, drag the activity block from the palette to the operation.

For more information about the parts of an operation and adding activities to operations, see Operation Creation and Configuration.

Configuring an API Activity

Follow these steps to configure an API Request or Response activity:

Step 1: Enter a Name and Provide a Schema

  • Name: Enter a name to use to identify the API activity. The name must be unique for each API Request or Response activity and must not contain forward slashes (/) or colons (:).
  • Provide Request Schema or Provide Response Schema: The request or response schema defines the structure of data that is used by the API Request or Response activity, respectively. Whether a file schema is required depends on if the API Request or Response activity is used as the source or target, respectively, of a transformation (see When to Use a Schema). For instructions on completing this section of activity configuration, refer to Schemas Defined in an Activity.

  • Save & Exit: If enabled, click to save the configuration for this step and close the activity configuration.
  • Next: Click to temporarily store the configuration for this step and continue to the next step. The configuration will not be saved until you click the Finished button on the last step.
  • Discard Changes: After making changes, click to close the configuration without saving changes made to any step. A message asks you to confirm that you want to discard changes.

Step 2: Review the Data Schemas

  • Data Schema: If provided during activity configuration, the request or response data schema is displayed. If the operation uses a transformation, the data schemas are displayed again later during the transformation mapping process, where you can map to target fields using source objects, scripts, variables, custom values, and more. You can also define schemas directly in a transformation.

  • Add Plugin(s): Plugins are Jitterbit- or user-provided applications that extend Harmony's native capabilities. To apply a plugin to the activity, click to expand this section and select the checkbox next to the plugin to be used. For additional instructions on using plugins, including details on setting any required variables used by the plugin, see Plugins Added to an Activity.

  • Back: Click to temporarily store the configuration for this step and return to the previous step.
  • Finished: Click to save the configuration for all steps and close the activity configuration.
  • Discard Changes: After making changes, click to close the configuration without saving changes made to any step. A message asks you to confirm that you want to discard changes.

Next Steps

After configuring an API Request or Response activity, you can use it within an operation as described below. Once the operation is set up, select it in the configuration of the Jitterbit Custom API to expose the operation or operation chain as a consumable REST endpoint. 

Completing the Operation

After configuring an API Request or Response activity, complete the configuration of the operation by adding and configuring other activities, transformations, or scripts as operation steps. You can also configure an operation's operation settings, which include the ability to chain operations together that are in the same or different workflows.

Once an API Request or Response activity has been created, menu actions for that activity are accessible from the project pane in either the Workflows or the Components tabs, and from the design canvas. See Activity Actions Menu for details.

The operation patterns that API activities can be used with depend on whether the activity provides data (as a source) or receives data (as a target) in an operation, as described below in Used as a Source and Used as a Target.

When ready, deploy and run the operation and validate behavior by checking the operation logs.

Used as a Source

API Request activities can be used as a source with these operation patterns:

Other patterns are not valid using API Request activities that are used as a source.

NOTE: Operations that begin with an API or API SOAP Request activity cannot be executed manually using the operation Deploy and Run or Run options. Instead, these operations require data that is provided when an API call is made using an API exposed through API Manager.

A typical use case is to use an API Request activity and an API Response activity in an operation chain, where the first operation is triggered by an API and the second operation runs on success of the first operation. Both operations in this example use the Transformation Pattern.

In this example, an API triggers the operation Insert Customer Request to run. The API Request activity (API Request) generates a response structure that is received by the transformation (API to Database), which is then inserted in a database using a Database Insert activity (Insert Response).

On success of the operation Insert Customer Request, the operation Query Customer Response runs. A Database Query activity (Query Request) generates a response structure that is received by the transformation (Database to API), which is then returned to the API by an API Response activity (API Response).

Used as Target

API Response activities can be used as a target with these operation patterns:

Other patterns are not valid using API Response activities that are used as a target.

A typical use case is to use an API Response activity multiple times within an operation chain to handle different error responses. Both operations in this example use the Transformation Pattern.

In this example, in the operation Get Employee Data, the Validate Parameters script is used to provide input for a Database Query activity (Query Request), which generates a response structure that is received by the transformation (Database to API) and returned to the API by an API Response activity (API Response).

On failure of the operation Get Employee Data, the operation Send Failure Response runs. The script Parse Failure Message is used to override the HTTP error code response for a Jitterbit Custom API using the Jitterbit variable jitterbit.api.response.status_code and provide the input for the transformation Format Failure Response, which is then returned to the API by an API Response activity (API Response).

Additional Examples

Other examples using API or API SOAP activities as sources or targets in an operation include Capturing Data Changes with a Harmony API or HTTP Endpoint and Configuring Outbound Messages with Harmony API. (These patterns use Design Studio as an example, but the same concepts can be applied in Cloud Studio.)

Configuring the Jitterbit Custom API

After the operation setup is complete, complete the configuration of the Jitterbit Custom API using API Manager. To configure a Jitterbit Custom API, refer to Custom API and OData Service Configuration.

Note that after you have configured a Jitterbit Custom API to call a Cloud Studio operation, you cannot delete the operation without first changing the API's configuration so it no longer calls the operation.


  • No labels