ÃÛ¶¹ÊÓƵ

DocumentationCampaignCampaign technotes

Migration of Campaign technical operators to ÃÛ¶¹ÊÓƵ Developer Console migrate-tech-users-to-ims

Last update: Fri Jun 21 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin

As part of the effort to reinforce security and authentication process, starting with Campaign v8.5, the authentication process to Campaign v8 is being improved. Technical operators can now use the to connect to Campaign. Learn more about the new server to server authentication process in .

A technical operator is a Campaign user profile which has been explicitly created for API integration. This article details the steps required to migrate a technical operator to a technical account via the ÃÛ¶¹ÊÓƵ Developer console.

Are you impacted? ims-impacts

If you are making API calls from a system external to Campaign into either their Campaign Marketing instance or the Real-Time Message Center instance, you must migrate the technical operator(s) to technical account(s) through the ÃÛ¶¹ÊÓƵ Developer Console as detailed below.

This change is applicable starting Campaign v8.5, and will be mandatory starting Campaign v8.6.

Migration process ims-migration-procedure

Follow the below steps to create technical account(s) within the ÃÛ¶¹ÊÓƵ Developer Console, and then use those newly created accounts to be able to change the authentication methods for all of your external systems making API calls in ÃÛ¶¹ÊÓƵ Campaign.

An overview of the steps are:

  • Creating a project within the ÃÛ¶¹ÊÓƵ Developer Console
  • Assigning the appropriate API’s to the newly created project
  • Granting the needed Campaign Product Profiles to the project
  • Updating your APIs to use the newly created technical account credentials
  • Remove the legacy technical operators from your Campaign instance

Prerequisites for the migration ims-migration-prerequisites

For API calls into the Message Center instance(s), a product profile should have been created during the upgrade to Campaign v8.5 or during provisioning of the instance. This product profile is named:

campaign - <your campaign instance> - messagecenter

If you have already been using IMS based authentication for user access to Campaign then the product profiles needed for the API calls should already exist within the Admin Console. If you use a custom operator group within Campaign for the API calls to the Marketing instance, you must create that product profile within the Admin Console.

For other cases, you must reach out to your ÃÛ¶¹ÊÓƵ Transition Manager so that ÃÛ¶¹ÊÓƵ technical teams can migrate your existing Operator groups and Named rights to the Product Profiles within the Admin Console.

Step 1 - Create your Campaign Project within the ÃÛ¶¹ÊÓƵ Developer Console ims-migration-step-1

Integrations are created as part of a Project within ÃÛ¶¹ÊÓƵ Developer Console. Learn more about Projects in .

You can use any project previously created by you or you can create a new project. The steps to create a project are detailed in the . You can find key steps below

To create a new project, click Create new project from the main screen in the ÃÛ¶¹ÊÓƵ Developer Console.

You can use the Edit project button to rename this project.

Step 2 - Add APIs to your project ims-migration-step-2

From the newly created project screen, add in the API’s needed to be able to use this project as a Technical Account for your API calls to ÃÛ¶¹ÊÓƵ Campaign.

To add APIs to your project, follow these steps:

  1. Click on Add API to select the APIs to add to your project.
  2. Select and add the ÃÛ¶¹ÊÓƵ Campaign API to your Project by checking the box in the upper right corner of ÃÛ¶¹ÊÓƵ Campaign card which appears when you hover the mouse over the card
  3. Click Next at the bottom of the screen.

Step 3 - Select the authentication type ims-migration-step-3

In the Configure API screen, select the authentication type needed. OAuth Server-to-Server Authentication is required for this project. Ensure it is selected and click Next at the bottom of the screen.

Step 4 - Select the product profiles ims-migration-step-4

As described in the prerequisites section you must assign the appropriate product profiles to be used by the project. In this step, you must select the product profile or profiles to be used by the technical account being created.

If this technical account is used to make API calls to the Message Center instance, be sure to select the ÃÛ¶¹ÊÓƵ create product profile which ends with messagecenter.

For API calls to the Marketing instance(s) select the product profile corresponding to the instance and Operator Group.

Once the needed product profiles have been selected click on Save configured API at the bottom of the screen.

Step 5 - Add the I/O management API to your project ims-migration-step-5

From the project screen, click the + Add to Project and choose API in the upper left of the screen to be able to add the I/O Management API to this project.

In the Add an API screen, scroll down to find the I/O Management API card. Select it by clicking the checkbox that appears when you hover over the card. Then click Next at the bottom of the screen.

In the Configure API screen, the OAuth Server-to-Server authentication is already existing. Click Save configured API at the bottom of the screen.

This takes you back to the Project screen within the I/O Management API of the newly created project. Click on the project name in the breadcrumbs at the top of the screen to be taken back to the main Project Details page.

Step 6 - Verify the project setup ims-migration-step-6

Review your project to ensure it looks similar to the below with the I/O Management API and ÃÛ¶¹ÊÓƵ Campaign API visible in the Products and Services section and OAuth Server-to-Server in the Credentials section.

Step 7 - Validate your configuration ims-migration-step-7

To try out the connection, follow the steps detailed in the  for generating an access token and copy the Sample cURL command provided. You can create a soap call using these credentials to test that you can authenticate and connect to the ÃÛ¶¹ÊÓƵ Campaign instance(s) correctly. We recommend doing this validation prior to making all of the changes to the third-party API integrations.

Step 8 - Update the third-party API Integrations ims-migration-step-8

You must now update all of the API Integrations making calls into ÃÛ¶¹ÊÓƵ Campaign to use the newly created Technical Account.

For further more details about API integration steps, including a sample code for smooth integration, refer to .

Below are sample SOAP calls showing the before and after migration calls for the third party systems.

When using ÃÛ¶¹ÊÓƵ Identity Management System (IMS) authentication, to generate a WSDL file, you should add the Authorization: Bearer <IMS_Technical_Token_Token> in the postman call:

curl --location --request POST 'https://<instance_url>/nl/jsp/schemawsdl.jsp?schema=nms:rtEvent' \--header 'Authorization: Bearer <Technical account access token>'

Once the migration process is achieved and validated, the Soap Calls are updated as below:

  • Before the migration: there was no support for Technical account access token.

    code language-sql 
    POST /nl/jsp/soaprouter.jsp HTTP/1.1
Host: localhost:8080
Content-Type: application/soap+xml;
SOAPAction: "nms:rtEvent#PushEvent"
charset=utf-8

<?xml version="1.0" encoding="utf-8"?>  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:nms:rtEvent">
<soapenv:Header/>
<soapenv:Body>
    <urn:PushEvent>
        <urn:sessiontoken>SESSION_TOKEN</urn:sessiontoken>
        <urn:domEvent>
            <!--You may enter ANY elements at this point-->
            <rtEvent type="type" email="name@domain.com"/>
        </urn:domEvent>
    </urn:PushEvent>
</soapenv:Body>
</soapenv:Envelope>

  • After the migration: there is support for Technical account access token. The access token is expected to be supplied in Authorization header as Bearer token. Usage of session token should be ignored here, as shown in the below soap call sample.

    code language-sql 
    POST /nl/jsp/soaprouter.jsp HTTP/1.1
Host: localhost:8080
Content-Type: application/soap+xml;
SOAPAction: "nms:rtEvent#PushEvent"
charset=utf-8
Authorization: Bearer <IMS_Technical_Token_Token>

<?xml version="1.0" encoding="utf-8"?>  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:nms:rtEvent">
<soapenv:Header/>
<soapenv:Body>
    <urn:PushEvent>
        <urn:sessiontoken></urn:sessiontoken>
        <urn:domEvent>
            <!--You may enter ANY elements at this point-->
            <rtEvent type="type" email="name@domain.com"/>
        </urn:domEvent>
    </urn:PushEvent>
</soapenv:Body>
</soapenv:Envelope>

Step 9 - (optional) Update the technical account operator within the Campaign client console ims-migration-step-9

This step is optional and only available within the Marketing Instance(s), not within any Message Center instance. If specific folder permissions or named rights have been defined for the Technical Operator not via the assigned Operator Group(s). You would now need to update the newly created Technical Account user in the Admin Console to grant the folder permissions or named rights required.

Note that the Technical Account user will NOT exist in ÃÛ¶¹ÊÓƵ Campaign until at least one API call is made to the Campaign Instance, at which time IMS will create the user within Campaign. If you are unable to locate the technical users within Campaign, ensure you have been able to successfully send an API call as outlined in Step 7.

  1. To apply the changes needed for the new Technical Account User, locate them within the Campaign client console by email address. This email address was created during the Project Creation and Authentication steps above.

    You can locate this email address by clicking on the OAuth Server-to-Server heading in the Credentials section of the Project.

    In the Credentials Screen, scroll down to locate the **Technical Account Email **and click the Copy button.

  2. You now need to update the newly created technical operator in ÃÛ¶¹ÊÓƵ Campaign client console. You must apply the existing technical operator folder permissions to the new technical operator.

    To update this operator, follow these steps:

    1. From Campaign client console explorer, browse to the Administration > Access Management > Operators.
    2. Access the existing technical operator used for APIs.
    3. Browse to the folder permissions, and check rights.
    4. Apply the same permissions to the newly created technical operator. This operator’s email is the Technical Account Email value copied earlier.
    5. Save your changes.
CAUTION
The new technical operator must have made at least one API call to be added to Campaign client console.

Step 10 - Remove the old technical operator from ÃÛ¶¹ÊÓƵ Campaign ims-migration-step-10

Once you have migrated all of the third-party systems to use the new Technical Account with IMS Authentication you can delete the old technical operator from the Campaign client console.

You do this by logging into the Campaign client console, navigating to Administration > Access Management > Operators and locating the old Technical Users and deleting them.

recommendation-more-help
c14bd44c-7b5f-474a-888d-1c2baee5a247