Web Services Connection Profiles

The following topics describe connection profiles for web services:

• ConnectionProfile:WebServices

• ConnectionProfile:Web Services REST

• ConnectionProfile:Web Services SOAP

ConnectionProfile:WebServices

9.0.20.220 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 one 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 any 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>: Type one of the following: <HTTP Header>: Start with the character @ for the job and then the header name. <HTTP Parameter Name>: Start with the character # for the job and then the parameter name. <value>: Type 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 not expose 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 database and is available to all Agents, versions 9.0.20 or higher. 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 not expose this value in the code.
Centralized	Determines whether to create a centralized connection profile, which is stored in the Control-M database and is available to all Agents, versions 9.0.20 or higher. 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