Interaction Model

This page explains how different parts of your connected system plug-in determine what a designer sees when creating connected systems and integrations, and how those objects execute. This includes:

You define these behaviors by extending classes found in the Core and Client SDK libraries. References on this page generally point to classes in the Client library.

Selecting a Connected System

create a connected system/create_connected_system_modal.png

When your plug-in is installed, all connected-system-template definitions in the plug-in manifest will appear in the Create Connected System dialog. The names and descriptions are pulled from internationalization bundles and you provide the logo icons in your plug-in package.

Configuring a Connected System

All connected systems have inputs for Name and Description, but you define the other fields by implementing the getConfiguration method in the SimpleConnectedSystemTemplate class (or one of it's subclasses). You decide what information is needed from the designer to connect to your target system. We've got a long list of examples showing how to configure different types of fields using the getConfiguration method.

See also:

Testing a Connected System

If you extend SimpleTestableConnectedSystemTemplate, you'll automatically get a Test Connection button at the bottom of your connected system configuration. When the designer clicks this button, it calls the testConnection method, which returns a TestConnectionResult, and uses the result to indicate whether the connection was successful or not.

See also:

Authorizing a Connected System

If you extend SimpleOAuthConnectedSystemTemplate you'll automatically get an Authorize button at the bottom of your connected system configuration. When the designer clicks this button it calls the getOAuthConfiguration method and launches the OAuth 2.0 authorization process.

See also:

Note: The getOAuthConfiguration method is also used to launch the OAuth 2.0 authorization process when designers click the Authorize link in the Integration dialog. The getOAuthConfiguration method is also used when users click on a link generated using a!authorizationLink().

Selecting an Integration Operation

When a designer creates an integration from your connected system, your plug-in controls the list of operations that the designer can chose from. All integration-template definitions within the connected-system-template in the plug-in manifest will appear in the Operation dropdown list. The names and descriptions are pulled from internationalization bundles. If you only define one integration-template, the designer won't see the dropdown and the operation will be selected automatically.

Configuring an Integration

For a given operation, you define what information is needed from the designer to configure a specific integration to the external system by implementing the getConfiguration method in the SimpleIntegrationTemplate class. The getConfiguration method works the same with integrations as with connected systems, but with integrations you have even more options to change the configuration fields depending on input from the designer. The same list of examples that applies to connected system configuration can be used for integrations too.

See also:

Testing an Integration

When designers test an integration, it calls the execute method in the SimpleIntegrationTemplate class, passing in the configuration values provided by the designer. The IntegrationResponse returned by execute is used to determine the result of the test (success or failure) and to show the result or error details.

When an integration fails, designers rely on the information in the IntegrationResponse to correct any problems. This includes the error message and Time breakdown on the Result tab, and the diagnostics shown on the Request and Response tabs.

See also:

Executing an Integration

When an integration is run from an interface, process model, or web API, the execute method in the SimpleIntegrationTemplate class is called (just like when testing an integration). Diagnostic information isn't needed when executing the integration in these cases. You can use the isDiagnosticsEnabled method in the ExecutionContext class to determine when to include them (if you get false from the executionContext.isDiagnosticEnabled then you don’t need to populate the diagnostics).

See also:

FEEDBACK