Example Use Cases

Version 23.4.8839


Example Use Cases


This section outlines common use cases that require a combination of API requests to accomplish.

Insert a File into the Workflow

POSTing to the Files Resource adds a file to the Send, Receive, or Sent folders for a particular connector. To insert a file into the workflow, POST the file to the Send folder for the first connector that should process the file. For example:

POST http://mydomain.com:8001.com/api.rsc/files
{
    "ConnectorId":"myConnector",
    "Folder":"Send",
    "Filename":"test.txt",
    "Content":"VGhpcyBpcyBhIHRlc3Qu"
}

Note that the Content parameter includes the base64-encoded content of the file.

If the target connector has Send Automation enabled, the file will automatically be processed. Otherwise, an additional call to the sendFile Action is required to instruct the connector to process the file. For example:

POST http://mydomain.com:8001/api.rsc/sendFile
{
  "ConnectorId":"myConnector",
  "File":"test.txt"
}

Retrieve the Log File for a Specific Transaction

The getTransactionLogs Action retrieves the log file for a specific action. Invoking this Action requires knowing the MessageId for the relevant transaction. The MessageId can be found by querying the Transactions Resource first (the Transactions Resource returns metadata about the transaction, but not the transaction log file itself).

The GET query to the Transactions Resource should include any filters necessary to identify the specific transaction unless the result set can be parsed by some other process to find the MessageId for the desired transaction. For example:

GET http://mydomain.com:8001/api.rsc/transactions(connectorId='myAS2Connector',Filename='myFile.edi')

The JSON body of the response will include the MessageId for the specific transaction. Use this MessageId in the getTransactionLogs call along with the other required parameters ConnectorId and Direction (Send or Receive). The IncludeContent parameter should be set to True to include the contents of the log file in the response. For example:

POST http://mydomain.com:8001/api.rsc/getTransactionLogs
{
	"ConnectorId":"myConnector",
	"Direction":"Send",
	"MessageId":"message_id_from_earlier",
	"IncludeContent":"True"
}

The Content parameter of the response will hold the base64-encoded log file contents.

Call Admin API from ArcScript

You can use ArcScript to send arc:call commands to the Admin API. Each call must start with api.rsc/.

The following limitations apply to this feature:

  • OData query syntax is not supported.
  • Rate limiters are not applied.
  • If the script is executed from the Admin Console directly, the user will be the currently logged-in user.
  • If the script is executed by an automation service, the IP address in an audit will be 127.0.0.1.

Retrieve Connectors

The following example is an isolated arc:call command used to retrieve the connectors resource:

<arc:call op="api.rsc/connectors" httpmethod="get" authtoken="6o6B3m4r3F8z6m4R3d1k" out="o">

This command consists of the following components:

  • op=”api.rsc/connectors” Sets the op (operation) parameter to call the Admin API (using api.rsc/) and retrieve the connectors resource.
  • httpmethod=”get” Designates the command as a GET command.
  • authtoken=”6o6B3m4r3F8z6m4R3d1k” Passes the specified token to the authtoken parameter. This can be obtained on the Settings page under the Users section.
  • out=”o” Assigns the connector returned by the command to o.

The following ArcScript code uses this arc:call command to create a list of all existing connectors:

<!-- Define an empty attribute to store a comma separated list of connectors and their types -->
<arc:set attr="result.connectors" value=""/>

<!-- List all existing connectors -->
<arc:call op="api.rsc/connectors" httpmethod="get" authtoken="test0:8s9T7b7m5Y5k3i5P2s6x" out="o">
  <arc:set attr="result.connectors" value="[o.connectorid]([o.connectortype]),[result.connectors]"/>
</arc:call>

Create and Modify a Connector

The following example issues a POST command to the Admin API to create a new Script connector in the flow:

<arc:set attr="new.connectorid" value="Script1"/>
<arc:set attr="new.connectortype" value="Script"/>
<arc:call op="api.rsc/connectors" httpmethod="post" authtoken="test0:8s9T7b7m5Y5k3i5P2s6x" in="new">
</arc:call>

After this new connector is created, you can issue a command to the Admin API to get the LogLevel value of the newly-created Script connector:

<arc:set attr="read.connectorid" value="Script1"/>
<arc:call op="api.rsc/connectors" httpmethod="get" authtoken="test0:8s9T7b7m5Y5k3i5P2s6x" in="read" out="o">
  <arc:set attr="result.new:old_loglevel" value="[o.loglevel]" />
</arc:call>

You can also update the LogLevel of the Script connector with a PUT command:

<arc:set attr="update.connectorid" value="Script1"/>
<arc:set attr="update.loglevel" value="Debug"/>

<arc:call op="api.rsc/connectors" httpmethod="put" authtoken="test0:8s9T7b7m5Y5k3i5P2s6x" in="update" out="o">
</arc:call>

Use the Admin API with an External Application (CORS)

You can configure cross-origin resource sharing (CORS) for the Admin API by navigating to the Admin API tab of the Settings page. CORS allows browser-based clients to connect to Arc. Without CORS, browser-based scripts cannot connect to Arc because of the same-origin policy enforced by the browser. This policy restricts client-side scripts and documents from loading resources outside their origin. The origin of a script consists of the protocol, host, and port.

  • Enable cross-origin resource sharing (CORS) Whether or not CORS is enabled. The rest of these options are only available when you check this box.
  • Allow all domains without ‘*‘ If enabled, domain origins are not restricted to a specific list.
  • Access-Control-Allow-Origin The comma-delimited list of domain origins to allow. Included as an HTTP response header.
  • Access-Control-Allow-Credentials Whether or not user credentials such as cookies are allowed in cross-origin requests. Included as an HTTP response header.
  • Access-Control-Allow-Methods The comma-delimited list of methods to allow. Included as an HTTP response header.
  • Access-Control-Allow-Headers The comma-delimited list of headers to allow. Included as an HTTP response header.
  • Access-Control-Max-Age The maximum duration (in seconds) that Access-Control response header values can be cached.