Media Type Mapping in External Service Registrations

Mapping Media Types During Registration

If you attempt to register a schema that includes a nonsupported media type, you’re asked to provide a mapping on the Associate operations with supported media types page.

Note The Associate operations with supported media types page isn’t shown during registration, unless there’s a nonsupported media type specified in the schema.

To associate operations with a supported media type:

1. Note the first nonsupported media type on the left.
2. Map the non supported media type to a supported media type by selecting a supported media type from the pull-down menu directly to the right.
3. If there are additional nonsupported media types in the list, continue down the list and select a mapping for each nonsupported media type listed.
4. Click Next.

Continue registration by selecting operations, as described in step #10 of Register an External Service.

Mapping Media Types with Metadata API

To manually map a media type, the nonsupported media type must be mapped to a supported media type as a mapping in the field serviceBinding of the ExternalServiceRegistration metadata file.

To demonstrate the manual method of mapping media types, consider this Acme Bank example.

Acme bank specifies an OpenAPI 2.0 service for their credit rating service. It defines its own media type for handling the JSON compatible payload: application/x-acme-json:

{  
   "swagger":"2.0",
   "info":{  
      "description":"A service for checking credit for an account.",
      "version":"1.0.0",
      "title":"Credit Decision"
   },
   "host":"<ACME's host>",
   "paths":{  
      "/account/credit-rating":{  
         "get":{
            "operationId":"getCreditRating",  
            "summary":"Evaluates credit rating for offered payment terms.",
            "consumes":[  
               "application/x-acme-json"
            ],
           "produces":[  
               "application/x-acme-json"
            ],
            "parameters":[{
               "description":"Account",
               "in":"body",
               "name":"body",
               "required":true,
               "schema":{  
                  "$ref":"#/definitions/Account"
               }
            }],
            "responses":{
               "200":{  
                  "description": "Credit rating",
                  "schema":{  
                     "$ref":"#/definitions/CreditRating"
                  }
               }
            }
         }
      }
   },
   "definitions":{  
      "Account":{  
         "type":"object",
         "properties":{  
            "accountId":{  
               "type":"string"
            },
            "accountHolder":{
                "type":"string"
            }
         }
      },
      "CreditRating":{  
         "type":"object",
         "properties":{  
            "creditRating":{  
               "type":"string"
            }
         }
      }
   }
}                    

To map the BankService media type to the supported media type application/json, open a command-line terminal. Create a directory in which to retrieve the external service’s metadata.

> mkdir BankService
> cd BankService

Create the manifest package.xml for the external service metadata for your BankService to retrieve from your organization:

> touch package.xml

Edit the package.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>BankService</members>
        <name>ExternalServiceRegistration</name>
    </types>
    <version>53.0</version>
</Package>

Retrieve the metadata for the external service with the Salesforce CLI command after successful authentication to your organization:

> sf project retrieve start --target-metadata-dir . --manifest package.xml

Unzip the package zip with the metadata and navigate to the directory with the external service:

> unzip unpackaged.zip
> cd unpackaged/externalServiceRegistrations

Edit service bindings in the external service registration metadata file BankService.externalServiceRegistration. Don’t break the <serviceBinding> section (in bold) with line breaks as it breaks deserialization.

<?xml version="1.0" encoding="UTF-8"?>
<ExternalServiceRegistration xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>MediaTypeMap</label>
    <namedCredential>BankServiceEndpoint</namedCredential>
    <operations>
        <active>true</active>
        <name>getcreditrating</name>
    </operations>
    <registrationProviderType>Custom</registrationProviderType>
    <schema>{
     ...
     }
    </schema>
    <schemaType>OpenApi</schemaType>
 <serviceBinding>{&quot;compatibleMediaTypes&quot;
:{&quot;application/x-acme-json&quot;
:&quot;application/x-acme-json&quot;}}</serviceBinding>
    <status>Complete</status>
</ExternalServiceRegistration>

The service binding specifies in JSON format the nonsupported media types defined by this external service registration:

{"compatibleMediaTypes":{
    "application/x-acme-json":"application/x-acme-json"
}}

Map the nonsupported media type to the supported media type for the external service payload serialization:

{"compatibleMediaTypes":{
    "application/x-acme-json":"application/json"
}}

The updated metadata for the bank rating external service sample registration respects the media type mapping to the supported media type when deployed in a package:

<?xml version="1.0" encoding="UTF-8"?>
<ExternalServiceRegistration xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>MediaTypeMap</label>
    <namedCredential>BankService</namedCredential>
    <operations>
        <active>true</active>
        <name>getcreditrating</name>
    </operations>
    <registrationProviderType>Custom</registrationProviderType>
    <schema>{
     ...
     }
    </schema>
    <schemaType>OpenApi</schemaType>
    <serviceBinding>{&quot;compatibleMediaTypes&quot;
:{&quot;application/x-acme-json&quot;
:&quot;application/json&quot;}}</serviceBinding>
    <status>Complete</status>
</ExternalServiceRegistration>

Don’t break the <serviceBinding> section with line breaks as it breaks deserialization.

Save the edited external service registration metadata file and deploy it:

> cd ../..
> sf project deploy start --metadata-dir unpackaged

For more information, see:

• ExternalServiceRegistration
• Salesforce DX Developer Guide