Web Services Connection Profiles

The following topics describe connection profiles for web services:

ConnectionProfile:WebServices

Control-M for Web Services enables you to schedule standard web services, servlets, and RESTful web services.

A web service is XML-based software that enables electronic devices to communicate via intranet or the internet. Servlets are small, Java-based programs that run on web servers, can access databases in response to user input, and add dynamic content to web sites. RESTful web services conform to the Representational State Transfer (REST) software architectural model and are used to create APIs for web-based applications.

The following example shows how to define a WebServices connection profile.

  • This JSON defines a regular WebServices connection profile:

    Copy 
    "WSDL_CONNECT":
    {
       "Type": "ConnectionProfile:WebServices",
       "TargetAgent": "AgentHost",
       "TargetCTM": "CTMHost",
       "ServiceType": "WebServices",
       "Location": http://example.com/serverpolicy/Request.asmx?wsdl,
       "HttpAuthentication": "user1:password@realm1;"
    }

  • This JSON defines a RESTful web service connection profile:

    Copy 
    "WSDL_CONNECT":
    {
        "Type": "ConnectionProfile:WebServices",
        "TargetAgent": "AgentHost",
        "TargetCTM": "CTMHost",
        "ServiceType": "Rest",
        "Location": http://example.com/serverpolicy/Request.asmx?wsdl,
        "HttpAuthentication": "user1:password@realm1;user2:password@realm2",
        "LoginUrl": "http://abc.xyz.com/login",
        "LoginHeader": "Accept:*/*",
        "LoginBody": "{}",
        "JobPreset": "@SessionId:@Token"
    }

The following table describes the WebServices connection profile parameters.

Parameter

Description

TargetAgent

Determines the Agent where the connection profile deploys.

TargetCTM

Determines the Control-M/Server where the connection profile deploys. If there is only one Control-M/Server, it defaults to that Control-M/Server.

ServiceType

Determines one of the following types of service to connect with:

  • File: Local File System, for jobs that execute web services based on the WSDL source file located on the Agent machine.

  • WebServices: Web Service URL, for jobs that execute web services based on the WSDL source that is managed from a web server.

  • Rest: For jobs that execute REST services.

Location

Determines one of the following types of Web Service locations:

  • File (Local File System): The path to the directory containing the WSDL files.

  • WebServices (Web Service URL): A URL that points to the location of a specific WSDL file.

  • Rest: The base URL location to the RESTful services, excluding the specific resource context path.

HttpAuthentication

(Optional) Defines the specification for simple text authentication in the following format:

user1:password@realm1;user2:password@realm2

Rules:

  • Only one user per realm.

  • End a single set with a ;.

  • Separate multiple sets with ;.

LoginUrl

(REST services only): Defines the URL for the login request.

LoginHeader

(Optional, for REST services only) .

Defines additional HTTP headers that are required in the login request in the following format:

<name>=<value>

Rule: For multiple headers, separate name-value pairs with :.

LoginBody

(Optional, REST services only) Defines the text required in the login request body.

JobPreset

(REST services only):

Defines the HTTP header or parameter to add to each job request in the HTTP query URL, based on the login returned data and in the following format (separate multiple sets with ;):

<name>:<value>;<name>:<value>

  • <name>: Uses one of the following:

    • <HTTP Header>: Starts with the character @ for the job and then the header name.

    • <HTTP Parameter Name>: Starts with the character # for the job and then the parameter name.

  • <value>: Uses one of the following:

    • /: XPath from the login response data, then the XPath.

    • $: JSONPath from the login response data, then the JSONPath.

    • @: Header from the login response HTTP headers, followed by the header name:

      <@ | #><HTTP Header or Parameter Name>:</ | $ | @><XPath, JSONPath, or header name of the login response>

ConnectionProfile:Web Services REST

Web Services REST jobs enable you to design and execute single REST API calls.

The following examples show how to define a Web Services REST connection profile.

  • This JSON defines a connection profile using basic authentication:

    Copy 
    {
       "REST_BASIC_AUTH": 
       {
          "Type": "ConnectionProfile:Web Services REST",
          "Description": "",
          "Centralized": true,
          "WebServiceAuthenticationBasic":
          {
             "UsePreemptiveAuth": true,
             "User": "User Name",
             "Password": "Password"
          }
       }
    }   

  • This JSON defines a connection profile using OAuth2 authentication:

    Copy 
    {
       "REST_OAUTH2": 
       {
          "Type": "ConnectionProfile:Web Services REST",
          "Description": "",
          "Centralized": true,
          "WebServiceAuthenticationOauth2": {
             "Headers": [
                {
                   "key1": "value1"
                },
                {
                   "key2": "value2"
                }
             ],
             "Body": [
                {
                   "resource1": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d"
                },
                {
                   "resource2": "2ff814a6-3310-4ab8-85de-cd0e6f879c12"
                }
             ],
             "ApiUrl": "https://login.microsoftonline.com/tenantId/oauth2/token",
             "ContentType": "application/x-www-form-urlencoded",
             "ClientId": "7f477fa3-1a1f-4877-ba80-f39bb563f1b5",
             "ClientSecret": "*****",
             "BasicAuthentication": {
                "Password": "*****",
                "User": "jdoe"
             },
             "GrantTypePassword": {
                "User": "abc",
                "Password": "*****"
             }
          }
       }
    }   

  • This JSON defines a connection profile using AWS authentication:

    Copy 
    {
       "REST_AWS": 
       {
          "Type": "ConnectionProfile:Web Services REST",
          "Description": "",
          "Centralized": true,
          "WebServiceAuthenticationAws":
          {
             "CustomServiceName": "batch",
             "Region": "eu-west-2",
             "AuthMethodAccessAndSecretKeys":
             {
                "AccessKey": "MYAWSACCESSKEY1234",
                "SecretAccessKey": "*****"
             }
          }
       }
    }

  • This JSON defines a connection profile using Google authentication:

    Copy 
    {
       "REST_GCP":
       {
          "Type": "ConnectionProfile:Web Services REST",
          "Description": "",
          "Centralized": true,
          "WebServiceAuthenticationGoogle":
          {
             "TokenType": "Access",
             "ServiceAccountKey": "{\"type\":\"service_account\",\"project_id\":\"sso-gcp-dba-ctm1-priv-cc30752\",\"private_key_id\":\"5197d05c5b8212bea944985cec74a34d6c1868aa\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\nprivate-key\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\bmc-wla-svc-02@sso-gcp-dba-ctm1-priv-cc30752.iam.gserviceaccount.com\,\"client_id\":\"116650586827623521335\",\"auth_uri\":\https://accounts.google.com/o/oauth2/auth\,\"token_uri\":\https://oauth2.googleapis.com/token\,  \"auth_provider_x509_cert_url\":\https://www.googleapis.com/oauth2/v1/certs\,\"client_x509_cert_url\":\https://www.googleapis.com/robot/v1/metadata/x509/bmc-wla-svc-02%40sso-gcp-dba-ctm1-priv-cc30752.iam.gserviceaccount.com\}"
          }
       }
    }   

The following table describes the Web Services REST connection profile parameters.

Parameter

Authentication Type

Description

Authentication Type

N/A

If the connection to the REST endpoint requires authentication, use one of the following objects to define the authentication type and to group together additional authentication parameters:

  • WebServiceAuthenticationBasic

  • WebServiceAuthenticationOauth2

  • WebServiceAuthenticationAws

  • WebServiceAuthenticationGoogle

User

Basic

Defines the basic authentication username.

Password

Basic

Defines the basic authentication password.

UsePreemptiveAuth

Basic

Determines whether to use preemptive authentication.

Valid Values:

  • True

  • False

Default: False

ApiUrl

OAuth2

Defines the OAuth2 web service URL.

ClientId

OAuth2

Defines the user ID associated with the Web Services REST user and application.

ClientSecret

OAuth2

Defines the secret (password) associated with the Web Services REST user and application. You can use Secrets in Code to hide this value in the code.

BasicAuthentication

OAuth2

Determines whether to add basic authentication to the OAuth2 authentication, by defining another user and password.

GrantTypePassword

OAuth2

Determines whether the OAuth2 web service requires an additional grant user and password, in addition to the client ID and secret, for added security.

ContentType

OAuth2

Defines the content type.

application/x-www-form-urlencoded

Headers

OAuth2

Defines OAuth2 header parameters, as an array of Key:Value pairs.

Body

OAuth2

Defines OAuth2 body parameters, as an array of Key:Value pairs.

Region

AWS

Defines the AWS region.

CustomServiceName

AWS

Defines the AWS service to access.

AuthMethodIAMRole

AWS

Determines that authentication of the AWS connection is based on an Identity and Access Management (IAM) role. The IAMRole parameter on the next level defines the IAM role for the AWS connection.
AuthMethodAccessAndSecretKeys AWS

Determines that authentication of the AWS connection is based on an AWS access key and secret, with the following parameters on the next level:

  • AccessKey: Defines the AWS account access key.

  • SecretAccessKey: Defines the AWS account secret access key.

TokenType

Google

Determines one of the following token types for GCP Access Control:

  • Access

  • Identity

ServiceAccountKey

Google

Defines a service account that is associated with an RSA key pair.

Centralized

All Authentication Types

Determines whether to create a centralized connection profile, which is stored in the Control-M/EM database and is available to all Agents.

You must set this parameter to true.

Valid Values:

  • true: Creates a centralized connection profile.

  • false: Creates a local connection profile, which is associated with and stored on a specific Agent.

Default: false

ConnectionProfile:Web Services SOAP

Web Services SOAP jobs enable you to design and execute single SOAP API calls.

The following examples show how to define a connection profile for a Web Services SOAP job.

  • This JSON defines a connection profile using basic authentication:

    Copy 
    "SOAP_BASIC_AUTH":
    {
       "Type": "ConnectionProfile:Web Services SOAP",
       "Description": "",
       "Centralized": true,
       "WebServiceAuthenticationBasic":
       {
          "UsePreemptiveAuth": true,
          "User": "User Name",
          "Password": "Password"
       }
    }

  • This JSON defines a connection profile with no authentication:

    Copy 
    "SOAP_NO_AUTH":
    {
       "Type": "ConnectionProfile:Web Services SOAP",
       "Description": "",
       "Centralized": true
    }

The following table describes the WebServices SOAP connection profile parameters.

Parameter

Description

UsePreemptiveAuth

Determines whether to use preemptive authentication.

Valid Values:

  • True

  • False

Default: False

User

Defines the basic authentication username.

Password

Defines the basic authentication password. You can use Secrets in Code to hide this value in the code.

Centralized

Determines whether to create a centralized connection profile, which is stored in the Control-M/EM database and is available to all Agents.

You must set this parameter to true.

Valid Values:

  • true: Creates a centralized connection profile.

  • false: Creates a local connection profile, which is associated with and stored on a specific Agent.

Default: false