14 Open Standards for Orchestrations

This chapter contains the following topics:

14.1 Understanding Open Standards for Orchestrations

Open standards for orchestrations allows external systems to discover orchestrations, including their inputs and outputs, by using the OpenAPI 2.0 standard (formerly known as "Swagger") or OpenAPI 3.0. This also enables products that conform to this standard to discover and execute orchestrations natively using this standard. Many products, including development, integration, automation, testing, and documentation tools, have libraries that support these standards.

Open standards for orchestrations gives you the ability to:

  • Return a list of orchestrations available on an AIS server secured by standard authentication.

  • Return a list of inputs and input types for an orchestration.

  • Return a list of outputs and output types for an orchestration.

  • Return the text description of an orchestration.

  • Discover orchestrations from any OpenAPI 2.0 or 3.0 compliant consumer.

This applies to any orchestrations that you have created.

14.2 Discovering Orchestrations Using Open Standards

To discover orchestrations, you use the open-api-catalog endpoint on the AIS Server.

The endpoint URL for OpenAPI (Swagger) 2.0 is:

http://<server>:<port>/jderest/v3/open-api-catalog

The endpoint URL for OpenAPI 3.0 is:

http://<server>:<port>/jderest/v3/open-api-catalog3

Note:

If you do not specify the version, the current version is used by default.

The discovery request must include authentication credentials for security. The request returns a standard Swagger 2.0 or OpenAPI 3.0 JSON formatted response with all of the orchestrations and related metadata that are available to the user whose credentials were used, subject to EnterpriseOne user-defined object security.

You can also add the orchestration name to the end of the URL to retrieve information only for that specific orchestration.

For example:

http://<server>:<port>/jderest/v2/open-api-catalog/MyOrchestration

You can import the JSON response into a third-party tool to review all the orchestrations. For example, importing into a documentation editor such as Swagger provides descriptions and other information, which enables you to document your own orchestrations.

Using a third-party tool, you can perform a POST or GET to execute a specific orchestration. However, if the orchestration inputs include an array, only the POST operation is available. A GET requires that the inputs are on the URL, while a POST requires the inputs as JSON in the request body.

14.2.1 XML Inputs and Outputs

You have the ability to execute an orchestration using XML as the input or output parameter content type.

For those applications that require producing and/or consuming XML rather than JSON, XML can be used as the transport format.

Setting the 'Accept' header on the orchestration execution request will return the output in XML format. Setting the 'Content-Type' header on the orchestration execution POST request will require the input to be in XML format.

Each orchestration input should be a single XML element, and the inputs should be contained within some outer parent element.

For example:

<inputs>
  <input1>value1</input1>
  <input2>value2</input2>
</inputs>

Note:

It is recommended that inputs do not have spaces or special characters as these characters require tokenizing in the XML.

Orchestrator Studio enables you to execute an orchestration using XML as the input or output parameter content type. You can use the Run Orchestrations page to test the orchestration with XML format. Setting the 'Accept' drop-down option to application/xml in the Output section will return the output in XML format. Setting the 'Content-Type' drop-down option to application/xml in the Input section will require the input to be in XML format.