Accounts

Automatically fetch data from your external web services with accounts. Learn what is an account, how it works, and how to create accounts for external web services.

Creating accounts

Whenever you use external web services (for example, Gmail, Dropbox, Evernote, etc.) in your workflow, IBM webMethods Integration platform accesses those services on your behalf to perform the specified tasks. To do this, you need to grant the necessary permissions and basic account details such as client ID, client secret to IBM webMethods Integration. This can be done using accounts.

The accounts are created and used at project level. Meaning, once you create an account for a specific project, you can use it in any workflow created under that project. However, it cannot be used outside that particular project. It is important to remember that, once you create an account (let’s say for Gmail), you can use the same account for all actions and triggers of Gmail connectors. You need not create a new account for different actions of the same service. Also, there is no limit to the number of authorizations you can create for a service.

Creating accounts is very easy with IBM webMethods Integration. We will understand how to create an account with the help of an example:

Let’s say you want to create an account for Trello. To do this, add the Trello connector on canvas and configure the Create Board action.

Here, you can see the Authorize Trello field. From here, you can create a new account, or access an existing account.

To create a new account, hover over the + button. You will see two options:

Default Authorization
(Or)

Creating accounts by generating keys

In the default authorization method, IBM webMethods Integration platform generates necessary keys to access your account data. To do so, you need to grant the IBM webMethods Integration platform the relevant permissions.

To create an account with default authorization method, click + and then select Default Authorization option.

This will take you to the Trello log in page. To authenticate yourself as a user, you need to log in to Trello by entering your credentials. Once this is done, (or if you are already logged in to Trello), the next page will ask you to authorize IBM webMethods Integration to perform certain actions on your behalf. Click ALLOW to proceed.

This will redirect you to the canvas where you will be prompted to provide a suitable name for the account you are about to create. You can optionally use the default name for the account.

Once this is done, click Add. This will add the specified Trello account for your IBM webMethods Integration account.

Now when you click on the Authorize Trello drop-down icon, you will see the Trello account you just created in the drop-down list.

You can now use this account in any workflow of the project for which you have created this account.

Creating accounts by using existing keys

If you have all the necessary keys and account details required to create an account, you can choose the second method. To do this, click the + button and select the (Or) option.

A pop-up window will appear on screen, where you will be prompted to enter the relevant keys/information required to create the Trello account.

Note

Apart from the Account Name field, the rest of the fields that appear in this form will vary depending on the application for which you are creating the account.

Once you have entered the required details, click Save.

This will create the account for the specified connector.

Now when you click on the Authorize Trello drop-down icon, you will see the newly created account in the drop-down list.

You can now use this account for any workflow created under the project for which you have created this account.

Creating accounts for connection-based connectors

There are some connectors, which don’t support OAuth, where you can grant IBM webMethods Integration the necessary permissions to generate keys on your behalf. For such connectors, you need to provide the necessary details required by the connector API to create an account.

Let’s say you want to create an account for Salesforce CRM.

To do so, add the Salesforce CRM connector on the canvas and select any action in the Select Action drop-down list.

When you click on the + button given beside the Connect to Salesforce CRM field, the Add Account window appears.
Apart from the Account Name field, the rest of the fields that appear in this form will vary depending on the application for which you are creating the account.

Note

Click here for information on the Account configuration fields.

Provide the necessary details and click Add. This will create the account for the specified connector.

Note

Click here to see some of the most common scenarios you may come across while configuring an Account.

Account configuration fields

The account configuration screen allows you to provide details to connect with the connector. The fields available may vary according to the selected connector.

Server URL

Provide the login endpoint to initiate communication with the SaaS provider.

Username

This is the user account name on the SaaS provider that the Account will use to connect to the SaaS provider.

Password

The password for the user name provided in the Username field.

JWT Keystore

Applicable when you select the OAuth V2.0 (JWT Flow) as the Authentication Type. The keystore used to encrypt the JWT payload. Use the same keystore which contains the private key of the certificate (Public keys) uploaded in your integration.

JWT Key Alias

Applicable when you select the OAuth V2.0 (JWT Flow) as the Authentication Type. This alias is the value that is used to sign the outgoing request from IBM webMethods Integration to the authentication server. It is auto-populated based on the keystore selected in the JWT Keystore field. This field lists all the aliases available in the chosen keystore. You must provide a key alias to sign the JWT payload.

Expiration Time(mins)

Applicable when you select OAuth V2.0 (JWT Flow) as the Authentication Type. Expiration Time (mins) is the time after which the JWT token expires. The generated access token might be valid post expiration time as well.

Access Token

Applicable when you select OAuth V2.0 (Authorization Code Flow) as the Authentication Type. This token is used for authentication and is issued by the Authorization Server. The access token is passed when you invoke any of the REST or SOAP API endpoints. The client application is responsible for storing and protecting this token. For authentication type selected as OAuth V2.0 (JWT Flow), IBM webMethods Integration implicitly gets an Access Token after you save the account.

Authorization Type

The type of HTTP authorization scheme to use for the connection. If you select none, no additional authorization scheme will be executed at run time. For example, when you specify a Username and Password, but do not specify a value for the Authorization Type, the user credentials are not inserted into an Authorization header. If you enter the username and password, then set the authorization type as basic. Basic refers to HTTP Basic Authentication. This option can be used if the connector requires or supports HTTP Basic authentication using a username and password.

Session Management

The session management scheme selection determines how a session or access token is handled for a given SaaS provider. If you select none, IBM webMethods Integration makes no attempt to refresh an established session or access token configured for a given SaaS provider. If you select fixed, IBM webMethods Integration attempts to refresh an established session or access token configured for a given SaaS provider, during the next operation, Flow service or Workflow execution, subject to, an interval configured using the Session Timeout (min) field, is exhausted. If you select idle, IBM webMethods Integration attempts to refresh an established session or access token configured for a given SaaS provider, during the next operation, Flow service or Workflow execution, subject to, the connection or session being idle for an interval configured using the Session Timeout (min) field. If you select auto, IBM webMethods Integration makes an attempt to refresh an established session or access token as specified by a given SaaS provider using the expires_in field value available in the refresh token response. If the SaaS provider does not provide the expires_in value, then the value configured for the Session Timeout (min) field prevails.

Session Timeout (min)

The number of minutes you want IBM webMethods Integration to wait before refreshing a session. The value should be slightly less than the session time-out value specified at the SaaS provider back end.
Note: The Session Management and Session Timeout configurations together determine how the session will be managed for a given SaaS provider.

Response Timeout

The number of milliseconds IBM webMethods Integration waits for a response before closing the socket connection to the back end. In case the network is slow or the back end processing takes longer than usual, increase the Response Timeout value. It is recommended to specify a value other than 0. If you specify 0, IBM webMethods Integration will wait indefinitely for a response.

Issuer

Applicable when you select the OAuth V2.0 (JWT Flow) as the Authentication Type. This is the Client ID, or Identifier, or name of the server or system issuing the JWT token.

Subject

Applicable when you select the OAuth V2.0 (JWT Flow) as the Authentication Type. This is the identifier or the name of the user this token represents.

Client ID

Applicable when you select the OAuth V2.0 (Authorization Code Flow) as the Authentication Type. This is a client identifier issued to the client to identify itself to the authorization server.

Client Secret

Applicable when you select the OAuth V2.0 (Authorization Code Flow) as the Authentication Type. This is a secret matching to the client identifier.

Refresh Token

Applicable when you select the OAuth V2.0 (Authorization Code Flow) as the Authentication Type. A token used by the client to obtain a new access token without involving the resource owner.

Refresh URL

Applicable when you select the OAuth V2.0 (Authorization Code Flow) as the Authentication Type. This is the provider specific URL to refresh an Access Token.

Retry Count on Response Failure

The number of times IBM webMethods Integration attempts to retry a request if the initial attempt to read a response fails. If an I/O error occurs, it will retry only if you have selected the Retry on Response Failure option.

Retry on Response Failure

Whether IBM webMethods Integration should attempt to resend the request when the response has failed, even though the request was sent successfully. Select this option if you want to re-establish the connection.

Trust Store Alias

Select the alias name of the IBM webMethods Integration trust store configuration. The trust store contains trusted certificates used to determine trust for the remote server peer certificates. You can also add a new Truststore from this field.

Keystore Alias

Select the alias for the IBM webMethods Integration key store configuration. This is a text identifier for the keystore alias. A keystore file contains the credentials (private key/signed certificate) that a client needs for authentication. You can also add a new Keystore from this field.

Client Key Alias

Alias to the private key in the keystore file specified in the Keystore Alias field. The outbound connections use this key to send client credentials to a remote server. To send the client’s identity to a remote server, you must specify values in both the Keystore Alias and the Client Key Alias fields.

Hostname verifier

Select a hostname verifier implementation. Guards against man-in-the-middle (MITM) attacks. The default is org.apache.http.conn.ssl.DefaultHostnameVerifier, which will enable hostname verification. Select org.apache.http.conn.ssl.NoopHostnameVerifier to disable hostname verification.

Use Chunking

Enable this option if you want to send or receive a large binary stream with a chunk size of 8192 bytes. This is applicable only if the back end supports HTTP/1.1 chunking.

Enable SNI

Server Name Indication (SNI) is an extension to the TLS protocol by which a client indicates which host name it is attempting to connect to at the start of the handshaking process. Enable this option if the SaaS provider offers SNI-based TLS connectivity, and if you want to connect to an SNI enabled SAAS provider to send the host name specified in the Server URL field, as part of the TLS SNI Extension server_name parameter.

SNI Server Name

If you want to explicitly specify a host name to be included as a part of the SNI extension server_name parameter, in case the host name is other than the host name specified in the Server URL field, specify the host name value in the SNI Server Name field.

Enable Connection Pooling

Select this option if you want to enable connection pooling for a connection. IBM webMethods Integration includes a connection management service that dynamically manages connections and connection pools based on configuration settings that you specify for the connection. A connection pool is a collection of connections with the same set of attributes. Connection pools improve performance by enabling Integrations to reuse open connections instead of opening new connections for every service request.
When you enable connection pooling, IBM webMethods Integration creates the number of connection instances you specified in the connection’s Minimum Pool Size field. Whenever an Integration needs a connection, IBM webMethods Integration provides a connection from the pool. If no connections are available in the pool, and the Maximum Pool Size has not been reached, IBM webMethods Integration creates one or more new connections (according to the number specified in the Pool Increment Size field) and adds them to the connection pool. If the pool is full (as specified in the Maximum Pool Size field), the requesting service will wait for IBM webMethods Integration to obtain a connection till 1 second, until a connection becomes available. Periodically, IBM webMethods Integration inspects the pool and removes inactive connections that have exceeded the expiration period of 1 second.

Minimum Pool Size

The minimum number of connection objects that remain in the connection pool at all times, if connection pooling is enabled. When the connector creates the pool, it creates this number of connections.

Maximum Pool Size

The maximum number of connection objects that can exist in the connection pool if connection pooling is enabled. When the connection pool has reached its maximum number of connections, the connector will reuse any inactive connections in the pool, or, if all connections are active, it will wait for a connection to become available.

Pool Increment Size

The number of connections by which the pool will be incremented, up to the maximum pool size, if connection pooling is enabled and connections are needed.

Keep Alive Interval

The keep alive interval in milliseconds defines the interval for which a connection will be kept alive, if the back end does not respond with a Keep-Alive header. A value > 0 keeps the connection alive for the specified value. The default value of -1 implies that the connection will be kept alive until a request fails due to a connection error.

Grant Type

Specify the grant type through which applications can gain Access Tokens and by which you grant limited access to your resources to another entity without exposing credentials. The Authorization Code grant type is used by confidential and public clients to exchange an authorization code for an access token. The Refresh Token grant type is used by clients to exchange a refresh token for an access token when the access token has expired.

Idle Timeout

The idle timeout interval in milliseconds defines the interval for which a connection will be kept alive if it’s not in use. A value > 0 keeps the connection alive for the specified value. The default value of -1 implies that the connection will be kept alive until a request fails due to a connection error.

Block Timeout (msec)

The number of milliseconds that IBM webMethods Integration will wait to obtain a connection with the SaaS provider before the connection times out and returns an error. For example, you have a pool with Maximum Pool Size of 20. If you receive 30 simultaneous requests for a connection, 10 requests will be waiting for a connection from the pool. If you set the Block Timeout to 5000, the 10 requests will wait for a connection for 5 seconds before they time out and return an error. If the services using the connections require 10 seconds to complete and return connections to the pool, the pending requests will fail and return an error message stating that no connections are available. If you set the Block Timeout value too high, you may encounter problems during error conditions. If a request contains errors that delay the response, other requests will not be sent. This setting should be tuned in conjunction with the Maximum Pool Size to accommodate such bursts in processing.

Expire Timeout (msec)

The number of milliseconds that an inactive connection can remain in the pool before it is closed and removed from the pool, if connection pooling is enabled. The connection pool will remove inactive connections until the number of connections in the pool is equal to the Initial Pool Size. The inactivity timer for a connection is reset, when the connection is used by the connector. This setting should be tuned in conjunction with the Initial Pool Size to avoid excessive opening and closing of connections during normal processing. The general recommendation is to keep the Expire Timeout value equal to the Session Timeout value.

Streaming Server URL

You can bring your data into Adobe Experience Platform through streaming ingestion. Streaming ingestion allows you to send data from client and server-side devices to the Adobe Experience Platform in real time. After registering a streaming connection you will have a unique URL which can be used to stream data to the Platform. The base path for streaming ingestion API for Data collection is: https://dcs.adobedc.net/.

Organization ID

The issuer, Organization ID from the Adobe I/O Console integration, in the format org_ident@AdobeOrg. Identifies your organization that has been configured for access to the Adobe I/O API.

Technical Account ID

The subject, your Technical Account ID from the Adobe I/O Console integration, in the format: id@techacct.adobe.com.

Audience

The audience for the token, your API Key from the Adobe I/O Console integration, in the format: https://ims-na1.adobelogin.com/c/api_key.

Sandbox Name

Adobe Experience Platform provides virtual sandbox environments which provide isolation and access control for Platform integrations. When making calls to Experience Platform APIs, a sandbox name must be supplied under the header x-sandbox-name. Provide the name of an available sandbox for your organization, for example, prod. The sandbox name is an all-lowercase identifier.

Region

An area specific value.

Signing Algorithm

Explicitly select the signing algorithm, for example, HMAC-SHA1 Signatures used to sign the message.

Authorization Token

The Alfabet Authorization Token as defined in the web.config file of the Alfabet Web Application on the server side, under the element.

Wait For Continue Time

The number of milliseconds that the client connection should wait for a 100 Continue response from the server when the Expect/Continue handshake is used.

Strict Transfer Encoding

Whether the connection validates the HTTP Transfer Encoding header.
Valid values
true: The connection validates the Transfer Encoding header and returns an error when the header is invalid.
false: The connection does not validate the Transfer Encoding header.

X-COUPA-API-KEY

The API Key received from the user account. Coupa REST APIs authentication requests require a unique API key generated in Coupa. All API requests must pass an X-COUPA-API-KEY header with an API key. A key can be created from the API Keys section of the Administration tab by an administrator. The key is a 40-character long case-sensitive alphanumeric code. The API key is associated with an API user who is the equivalent of an administrator in Coupa. Any changes to resources through the API are attributed to the API user.

Use CSRF Token

To prevent cross site request forgery, SAP C4C protects its resources by using a CSRF token. Select this option if you want IBM webMethods Integration to use the CSRF token key, received in the response from SAP C4C, to perform any state changing requests on SAP C4C. By default, the CSRF token is enabled by the SAP C4C back end. You must enable this option particularly when the entity state changing operation is invoked.

Metadata Caching

Select this option if you want the SAP C4C Application to cache the backend metadata. Caching of the metadata significantly increases the performance of a request sent through SAP C4C. If this option is selected, the cache will be refreshed every 12 hours. It is recommended to enable the metadata cache to increase the performance.

Validate Metadata

Whether to validate the $metadata xml during edm object creation. Select this option to enable the metadata validation.

Shopify API key

Shopify REST APIs authentication requests require a unique API key generated in Shopify. All API requests must pass an X-Shopify-Access-Token header with an API key.

Company ID

The company ID that SuccessFactors provided, when your company registered with them.

PubId

Enter the PubId (Profile ID) associated with your AddThis account. Refer this link to find your PubID (Profile ID of AddThis).

API Key

Enter the API key associated with your AddThis account. Refer this link to retrieve the API key associated with your AddThis account.

Domain

Enter the domain for your Aha account. If your account URL is https://example.aha.io, enter example.aha.io as the domain.

Signing Algorithm

The signing algorithm to use for an outbound AS2 message. The available options are MD5, SHA-1, SHA-256, SHA-384, and SHA-512.

Receive Signed Message

Select this option to receive a signed inbound AS2 message. If you select this option and the incoming AS2 message is not signed, then an Insufficient message security error is encountered and shared with the sender if MDN is requested by the sender.

Signature Verification Certificate

The certificate to use for verifying an inbound signed AS2 message.

Encrypt Message

Select this option to encrypt an outbound AS2 message.

Encryption Algorithm

The encryption algorithm to use for an outbound AS2 message.

Encryption Certificate

The certificate to use for encrypting an outbound AS2 message.

Decryption Keystore and Key Aliases

The keystore aliases and the key aliases in the keystore to use for decrypting an inbound AS2 message.

Request MDN

Whether you want the recipient to return an MDN to the sender. Select one of the following options:
None: The recipient of the AS2 message does not return an MDN to the sender.
Synchronous: The recipient of the AS2 message returns an MDN to the sender through the same HTTP connection used to send the original AS2 message.
Asynchronous: The recipient of the AS2 message returns an MDN to the sender through a different HTTP connection instead of the one used to send the original AS2 message.

Request Signed MDN

Select this option if you want the recipient to sign an AS2 MDN. Ensure that you also select an option in the Request MDN field if you want the recipient to sign and return an AS2 MDN.

Asynchronous MDN Endpoint

Type your endpoint URL that accepts an inbound AS2 MDN if you selected the Asynchronous option for Request MDN.

AS2 Version

Select the AS2 protocol version to use from the list.

Language Translator Service API Key

Enter the language translator service API key of your account.

Community

URL of the Igloo community to log in to, for example, https://{your_domain}.igloocommunities.com.

Auth Source

Specify the name of the MongoDB database against which you want to authenticate the user.

Replica Set

Enter the replica set for the specified database.

Managing project-level accounts

You can view, create, modify, and delete the accounts created under a specific project.

To do this, navigate to the relevant project, click Configurations, and click Connections.

Viewing accounts

In the Connections option under Workflow section in Configuration tab, you can view the list of all accounts created for all connectors under the specified project. It has following details:

Connector : The connector name for which you have created the account.
Configurations : The number of account(s) configured. If you have created multiple accounts for a single connector, you can view its list by clicking the drop down icon.
Used in : The account(s) being used in how many workflow(s) and operation(s).

Note

You can also create new accounts, or edit or delete the existing ones. To do so, click on the drop down arrow located at the left of the connector icon. On clicking, you can also view the workflow name in which you have created the account for this connector and the action name for which you have configured the account.

Creating accounts

You can create additional accounts for a specific connector by clicking on the + icon given against the existing account name. The procedure to create a new account remains same as explained here.

Note

You cannot create accounts for connection-based connectors from the Configurations tab.

Editing and deleting accounts

You can edit or delete the existing accounts. To edit or delete an account, click on the name of the account.

You will see two icons — Edit and Delete.

Editing accounts

Note

If you have created the account using the Default Authorization method, you can edit only the name of the account. For all other types of accounts, you can edit all details available in the form field.

You can access and edit accounts configured for a connector using the following options:

Go to the relevant project, click Connectors, and click the Predefined option.

a. To edit an Account, click the drop-down arrow located at the left of the connector icon. You will see the list of configured accounts for that connector. In our example, we have selected the PubNub connector.

b. Hover over the account name. You will see two icons - Edit and Delete. Click the Edit icon.

The Edit Account dialog box appears.

c. On the Edit Account dialog, click the Edit icon, update the relevant account connection details, and click Save.

Note

The name of the account connection cannot be changed.

Go to the relevant project and click Configurations > Workflow > Connections.

a. Click the drop-down arrow located at the left of the connector icon. You will see the list of configured accounts for that connector. In our example, we have selected the PubNub connector.

b. Click the drop-down arrow displayed on the right of the account name for the selected Account. You will see two icons - Edit and Delete. Click the Edit icon.

The Edit Account dialog box appears.

c. On the Edit Account dialog, click the Edit icon, update the relevant account connection details, and click Save. Note that the name of the account connection cannot be changed.

Note

The name of the account connection cannot be changed.
The existing values of the mandatory fields (for example, Client Key) are masked. You can update the masked value of any mandatory field by clicking the Edit icon on the relevant mandatory field, entering updated value, and then clicking Save.

Deleting accounts

To delete the account, click the Delete icon.

You will be prompted to confirm the delete action.

Click Delete. This will delete the specified account from your project.

If you have used the account in any workflow(s), you will be prompted to remove the account from the workflow(s) first.

Once this is done, go back to the Configurations tab, and repeat this procedure.

Managing workflow-specific accounts

All accounts used in a specific workflow can be viewed and deleted via Workflow Settings panel.

To do so, open the relevant workflow on canvas, click the Workflow Settings icon located at the top-right corner of the canvas, and click Accounts.

From here, you can view and delete the accounts used in the workflow.

Note

Deleting an account from the Workflow Settings panel, will only remove it from the current workflow. It will continue to be available in all other workflows till you delete it permanently from the Configurations tab.

Configuring OAuth V2.0 authentication

While creating an account, the user associates only one connection type or authentication scheme with an account. As some SaaS providers such as Salesforce CRM offer multiple authentication options to access their APIs, you now select different authentication types for the same application while creating an account.

Let’s look at an example to understand how OAuth V2.0 authentication works. Let’s say you want to create an account for Salesforce CRM and use OAuth V2.0 type of authentication.

To configure OAuth V2.0 authentication, add the Salesforce CRM connector on canvas and configure an account.

If you already have the operations created from OAuth V2.0 type account, then select one. Else create a new custom action. Read more about custom actions.

When you click on the + button given beside the Select Action field, the Add Custom Action window appears. Let’s look at how to set up OAuth V2.0 authentication.

Connect to an account

Here, you see the Select Authentication type field. The field lists the connection types based on the supported authentication schemes by the connector.

Click Select Authentication type drop-down list to view the connection types available for the selected application.
You will see the following options:

Credentials
OAuth V2.0 (Authorization Code Flow)
OAuth V2.0 (JWT Flow)

Select OAuth V2.0 (Authorization Code Flow)

Next, you see the Authorize Salesforce CRM field. From here, you can create a new account, or access an existing account.

Hover over the + button to create a new account. You will see two options:

Default Authorization
(Or) Custom auth

To create an account with the default authorization method, click + and then select Default Authorization option.

This will take you to the Salesforce login page. To authenticate yourself as a user, you need to log in to Salesforce by entering your credentials. Once this is done, (or if you are already logged in to Salesforce), the next page will ask you to authorize IBM webMethods Integration to perform certain actions on your behalf. Click ALLOW to proceed.

This will redirect you to the canvas where you will be prompted to provide a suitable name for the account you are about to create. You can optionally use the default name for the account.

Once this is done, click Add. This will add the specified Salesforce account for your IBM webMethods Integration account.

Now, when you click on the Authorize Salesforce CRM drop-down icon, you will see the Salesforce account you just created in the drop-down list.

You can now use this account in any workflow of the project for which you have created this account.