Connector Builder- Setup Configuration and Parameters

Connector configuration and parameters work together to solve various scenarios presented by API providers. When you set up your connector configuration, you define the information that you want to store with the connector. The information can include data that you collect from the user when they authenticate an instance of a connector. You can also store variables in the configuration that you can act on with parameters and hooks. You can also store information that you need to pass with each request to the API provider.

Parameters enable you to configure information that you need to send to an API provider with each request and how they expect to receive it. You can pass variables that you added to the configuration, the information provided by the user, specific values, and more.

Icon

The configuration and parameters that you define here affect all requests made by the connector. You will also define configurations and parameters specific to each endpoint when you set up resources.

Reserved Configurations

Each parameter that you set up when defining the authentication information is available as a connector configuration. The connector configuration also includes the properties of the connector: pagination information and base URL. The configuration Keys associated with the authorization and pagination parameters are reserved. You will receive an error if you try to create a configuration with a reserved configuration Key. The following table shows the reserved configuration Keys.

OAuth Keys Basic Keys Properties Keys Events and Bulk AWS Keys
oauth.basic.header username base.url Any keys beginning bulk. aws.api.key
oauth.user.refresh_time password pagination.type Any keys beginning event. aws.api.secret
oauth.user.refresh_token   pagination.max event.notification.instance.finder aws.region
oauth.user.refresh_interval   pagination.page.startindex event.vendor.type expires
oauth.user.token     event.poller.refresh_interval expires_in
oauth.api.key     event.notification.enabled  
oauth.scope     event.notification.callback.url  
oauth.token.url     event.poller.configuration  
oauth.api.secret     event.notification.subscription.id  
oauth.authorization.url     event.metadata  
oauth.token.refresh_url     event.helper.key  
oauth.callback.url        
oauth.request.authorization.type        
oauth.request.url        
oauth.token.revoke_url        
oauth.user.token.secret        

Set Up Connector Configuration

The connector configuration is the storage place for any data that you need to operate on with parameters and hooks. For example, if the API provider requires something specific with each request, you can add that to the configuration and then define a parameter that passes the data with each request. You can expose the configuration to the user so that they can supply the information when they authenticate. Or, if it is not user-specific information, you can store a default value in the configuration to act on later.

Before you set up configurations, review the  Connector Conventions so your connector will align with others in the Connectors Catalog.

To set up a configuration:

  1. Navigate to Configuration, and then click Add Configuration.
  2. Enter the name of the configuration. If you choose to show this on the UI, Axway AMPLIFY will show the configuration name as you define it here.

    As you type, we pre-populate the Key and Description.

  3. In Key, you can choose to update the value automatically created from the configuration name or leave it. The configuration Key identifies the configuration property in the connector configuration. You also use the configuration Key to refer to the configuration in parameters and hooks.
  4. In Type, select the type of configuration. Configurations can be text strings, boolean, or passwords.
  5. In Default, enter any default value for the configuration. If shown on the UI, a user can overwrite the default value.
  6. In Description, enter a brief description of the configuration. If the configuration appears in Axway AMPLIFY, the description is available as hover help.
  7. To make the configuration a required part of authentication, switch Required on.
  8. Switch Hide UI on to prevent the configuration from appearing on the UI when the user authenticates. By default, the configuration appears on the UI.
  9. Click Save.

Connector Configuration Parameters

Parameter Description Required
Name The visible name of the configuration as it appears in the Axway AMPLIFY UI. Y
Key The internal unique identifier for the configuration. The configuration key-value appears in the authentication JSON. You also refer to the configuration by configuration key in parameters and hooks. Y
Type The type of configuration, which can be any of the following: Y
  Text Area, Text Text 32, Text 64, Text 100, Text 128 — Identifies configurations that accept free text strings.  
  true/false and yes/no — Identifies configurations that accept boolean inputs.  
  password — Identifies configurations intended to collect passwords. Passwords are masked in Axway AMPLIFY.  
Required Identifies whether the configuration is required. Switch on to force a user to provide data when authenticating. Configurations not required, but that show in Axway AMPLIFY appears under Show Optional Fields. Y
Hide on UI Identifies whether the configuration appears in Axway AMPLIFY. Switch on to show the configuration in Axway AMPLIFY. The configuration appears to the user with the configuration name and the description as hover help text. Y
Configuration Description The description appears as hover help text. The text space available is limited, so write brief but useful descriptions. Y
Default Value The default value of the configuration. N

Set Up Connector Parameters

Connector parameters allow you to pass various properties with each request. You can create parameters that require user input or parameters that get their values from other sources. Use the connector parameters to configure required query parameters, searches, pagination, ids, and required fields. You can configure most required and optional parameters for most APIs using parameters and configurations. Map parameters that you send as part of the request from Axway AMPLIFY on the top row to parameters available to the resource at the API provider on the bottom row. 

Before you set up parameters, review the Connector Conventions so your connector will align with others in the Connectors Catalog. Each parameter includes information about how the parameter is used at Axway AMPLIFY and how the API provider expects to receive the parameter.

To define a parameter :

  1. Navigate to Configuration, and then click Add Parameter.
  2. Complete the top row of Axway AMPLIFY parameter information:
    • In Name, enter the name of the parameter. The name appears in the API documentation and should match any existing values. For example, if you choose a type of "configuration", the name must match the configuration key to which it refers.
    • In Type, select the source of the parameter. Refer to Axway AMPLIFY Parameter Type in the Connector Parameter Fields table.
    • If you want to switch the standard workflow where the parameters in the top row are part of the request from Axway AMPLIFY and want the parameters on the top row to represent the response from the API provider, click Source, and then select Response.
    • In Description, enter a brief description of the parameter. If the parameter appears in the API documentation, this description also appears.
  3. Complete the bottom row of API provider parameter information:
    • In Name, enter the name of the API provider's name for the parameter to map to.
    • In Type, select how the API provider receives the parameter. Refer to API Provider Parameter Type in the Connector Parameter Fields table.
  4. Click Save.

Connector Parameter Fields

Parameter Description Required
Axway AMPLIFY Parameter Name The parameter name acts as a key and provides values to the Parameter Types. Required
Axway AMPLIFY Parameter Type The source of the parameter value on the Axway AMPLIFY side. Y
  configuration — The value of the parameter is the value of the configuration identified by the configuration Key specified in the Parameter Name. The Parameter Name must match a configuration Key in the connector configuration.  
  header — The value is the request header parameter that matches the Parameter Name.  
  path — The value is the part of the request path that matches the Parameter Name.  
  body — The value is the part of the request body that matches the Parameter Name.  
  query — The value is the query parameter that matches the Parameter Name.  
  form — The value is the value of the key that matches the Parameter Name in the x-www-form-urlencoded body of a request. If a file, then use "file" as the Parameter Name.  
  multipart — The value is the value of the key that matches the Parameter Name in the x-www-form-urlencoded body of a request. If a file, then use "file" as the Parameter Name.  
  value — The value is the Parameter Name.  
  bodyField — The value is the value of the field in a request body that matches the Parameter Name.  
  prevBody - Axway AMPLIFY parameter type only. If chaining requests, the value is the part of the request body of the previous request in the chain that matches the Parameter Name.  
  prevBodyField - Axway AMPLIFY parameter type only. If chaining requests, the value is the field in the request body of the previous request in the chain that matches the Parameter Name  
Source Identifies the side that represents the source, or left side of the parameter. The default request identifies Axway AMPLIFY as the source. If you choose response, you effectively flip the Axway AMPLIFY and API provider sides. Y
Description A free text area to describe the parameter. N
API Provider Parameter Name The parameter at the API provider that equals the parameter that you are defining. Required
API Provider Parameter Type The destination of the parameter value on the API provider side.: Y
  configuration — Requests to the API provider pass the parameter value as part of the configuration.  
  header — Requests to the API provider pass the parameter value in the header.  
  path — Requests to the API provider pass the parameter value in the path.  
  body — Requests to the API provider pass the parameter value in the body.  
  query — Requests to the API provider pass the parameter value as a query parameter.  
  form — Requests to the API provider pass the parameter value as part of the x-www-form-urlencoded body of a request.  
  multipart — Requests to the API provider pass the parameter value as part of the x-www-form-urlencoded body of a request.  
  value — Requests to the API provider pass the parameter value as a value.  
  bodyField — Requests to the API provider pass the parameter value as a body field.  
  bodyToken — Requests to the API provider pass the parameter value as a body token.  
  no-op — Indicates that the API provider does not need to operate on the parameter. Use no-op if you use the parameter in hooks.  

Delete Configurations and Parameters

You can delete a connector configuration or parameter. When you delete the configuration or parameter, Axway AMPLIFY does not check for references in hooks or to other connector configurations.

To delete a configuration or parameter, click Delete.

Continue to the next step, Custom Hooks.

Related Links