Description
Many Cyara users are asking questions on how to create and manipulate campaigns using the 3.0 API. This article provides a step by step description on how to Create, Update, Execute, and Delete Campaigns using the Cyara API 3.0.
Authentication Step
A lot of API beginner users are experiencing issues with Authentication.
Cyara uses API Key for authentication instead of HTTP Basic auth. More on that you can find in the article that describes the Authentication Process.
Step 1: Create a Campaign
Swagger provides a description of the Cyara Campaign endpoints, however sometimes it is still not clear on how to create a campaign. The following example shows how to create a Velocity Campaign for the Voice Channel.
Prerequisites:
- Plan ID
- Plan Type
- Concurrent interactions (or ports)
- Attempts per second (APS)
- Test Case IDs
How to Get Object IDs?
Getting Test Case object IDs is easy if all of the Test Cases are created using APIs. If not, you can get a list of all of the test cases using the corresponding API Call:
GET https://[URL]/cyarawebapi/v3.0/accounts/[Account_ID]/testcases
The result of this query will be an object with a list of lists representing each of the test cases:
{
"firstPage": "https://[URL]/cyarawebapi/v3.0/accounts/1/testcases?pageno=1",
"lastPage": "https://[URL]/cyarawebapi/v3.0/accounts/1/testcases?pageno=4",
"nextPage": "https://[URL]/cyarawebapi/v3.0/accounts/1/testcases?pageno=2",
"previousPage": null,
"results": [
{
"accountId": 1,
"testCaseId": 3136,
"direction": "Inbound",
"channel": "Voice",
"name": "[ACTION] - Reboot AGD",
"folderPath": "Temp",
"stepCount": 5,
"lastModified": "2019-04-26T21:15:11.8071332Z",
"destination": "ext@ip",
"linkedCampaignCount": 0
},
{
"accountId": 1,
"testCaseId": 2125,
"direction": "Inbound",
"channel": "Voice",
"name": "[ACTION] - Reboot AGD",
"folderPath": "AGD MOBILE\\TEMPLATES",
"stepCount": 5,
"lastModified": "2019-02-22T19:44:33.8826725Z",
"destination": "ext@ip",
"linkedCampaignCount": 0
},... []
Test Cases will reside inside the results object
[results] = list1, list2, list3...
Plan IDs can be retrieved in a similar fashion:
GET https://[URL]/cyarawebapi/v3.0/accounts/[Account_ID]/plans
as a response Cyara will provide paginated list of Plans for the Account.
Creating Campaign:
Now, when we have all of the objects, we can create a campaign:
POST https://[URL]/cyarawebapi/v3.0/accounts/[Account_ID]/campaigns
{
"concurrency": 1,
"testCaseDistributionProfile": "RoundRobin",
"active": false,
"channel": "Voice",
"description": null,
"name": "Velocity Campaign Created with RestAPI#3",
"RunTime": "00:10:00",
"RequestedRunDate": "2021-06-15T18:16:33.2291904Z",
"ScheduledRunDate": "2021-06-15T18:16:33.2291904Z",
"planId": 25,
"planType": "Velocity",
"MaximumAps": 1,
"testCases": [
{
"probability": 100.0,
"testCaseId": [TestCase ID]
}
]
}
A successful response will look like:
200 OK
{
"campaignSync": {
"isActive": false
},
"pauseTimeBetweenRetries": null,
"maximumRetries": null,
"concurrency": 1,
"maximumAps": 1.0,
"testCaseDistributionProfile": "RoundRobin",
"active": false,
"campaignId": 3093,
"channel": "Voice",
"description": null,
"name": "Velocity Campaign Created with RestAPI#3",
"lastRunDate": null,
"requestedRunDate": "2021-06-15T18:16:33.2291904Z",
"scheduledRunDate": "2021-06-15T18:16:33.2291904Z",
"status": "None",
"plan": {
"planId": 25,
"type": "Velocity",
"name": "Velocity - 5 Ports",
"startDate": "2020-07-30T19:23:00Z",
"endDate": "2025-07-30T19:23:00Z"
},
"testCases": [
{
"calledNumber": "8002@192.168.11.99",
"probability": 100.0,
"testCaseId": [TestCaseID],
"name": "API_TC_Manual",
"folderPath": "\\",
"channel": "Voice",
"url": "https://[URL]/cyarawebapi/v3.0/accounts/[AccountID]/testcases/[TestCaseID]"
}
]
}
Step 2: Modifying the Campaign
The next step would be to add more test cases or change some parameters of the Campaign. For these purposes we have to use PUT request and a modified body:
PUT https://[URL]/cyarawebapi/v3.0/accounts/[AccountID]/campaigns/3093
{
"synchronized": {
"isActive": false
},
"maximumAps": 1.0,
"concurrency": 1,
"testCases": [
{
"testCaseId": 1856600,
"probability": 100
}
],
"planId": 25,
"active": false,
"channel": "Voice",
"name": "Velocity Campaign Created with RestAPI#4 - Updated",
"description": "Updated with the Cyara API 3.0",
"requestedRunDate": "2021-06-16T19:52:00Z",
"scheduledRunDate": "2021-06-16T19:52:00Z",
"testCaseDistributionProfile": "RoundRobin",
"planType": "Velocity"
}
Updated fields Are: Name, Description and Test Case ID.
In case of successful execution you should receive a 200 OK with a valid JSON of the Campaign properties.
Step 3: Running Campaign
The next step would be to add more test cases or change some parameters of the Campaign.
Running campaign is simple, but it is important to know that the campaign-runid object that Cyara API returns in the response is for the previous campaign run. It happens due to limitations of the Cyara's current architecture. Therefore it is important to follow next steps.
POST https://[URL]/cyarawebapi/v3.0/accounts/1005/campaigns/3093/execute
Step 4: Retrieving Campaign RunID
As mentioned above it is important to know that the campaign-runid object that Cyara API returns in the response is for the previous campaign run. It happens due to limitations of the Cyara's current architecture.
To retrieve the campaign RunID you need to get the current execution Date and Time in UTC format. After that you can run an API query to retrieve the RunID:
GET https://[URL]/cyarawebapi/v3.0/accounts/1005/campaigns/3093/runs?fromDate=2021-11-16T00:00:00Z
Response Body will contain the RunID:
{
"campaignId": 3093,
"campaignName": "Velocity Campaign Created with RestAPI#4 - Updated",
"accountId": 1005,
"firstPage": "https://[URL]/cyarawebapi/v3.0/accounts/1005/campaigns/3093/runs?fromdate=2021-11-16T00%3A00%3A00Z&pageno=1",
"lastPage": "https://[URL]/cyarawebapi/v3.0/accounts/1005/campaigns/3093/runs?fromdate=2021-11-16T00%3A00%3A00Z&pageno=1",
"nextPage": null,
"previousPage": null,
"results": [
{
"runId": 104884,
"startDate": "2021-11-16T21:44:35.4036169Z",
"endDate": "2021-11-16T21:44:52.0495884Z",
"result": "Success",
"campaignRunId": "e9f9a397-6ba8-4aa2-9639-efbc72374c2c",
"url": "https://[URL]/cyarawebapi/v3.0/accounts/1005/campaigns/3093/runs/e9f9a397-6ba8-4aa2-9639-efbc72374c2c"
}
],
"totalResults": 1,
"returnedResults": 1
}
Run ID can be found as a result['RunId'] (syntax may vary depending on the language that is used)
Step 5: Retrieving Campaign Results
As soon as we get the RunID of the campaign we can retrieve results of the campaign. The assumption here is that campaign is finished. If not, we will need to add another step to poll the campaign status.
GET https://[URL]/cyarawebapi/v3.0/accounts/1005/report/campaigns/3093/runs/104884/results?stepResults=true
In case of correct request Cyara API will return a paginated list of test results:
{
"firstPage": "https://[URL]/cyarawebapi/v3.0/accounts/1005/report/campaigns/3093/runs/104884/results?stepresults=true&pageno=1",
"lastPage": "https://[URL]/cyarawebapi/v3.0/accounts/1005/report/campaigns/3093/runs/104884/results?stepresults=true&pageno=1",
"nextPage": null,
"previousPage": null,
"results": [
{
"calledNumber": "8002",
"callingNumber": null,
"testRunTicketId": "43b6c65a-bc46-45be-bf47-647487fdf2e6",
"channel": "Voice",
"runDate": "2021-11-16T21:44:35.7392292Z",
"duration": "00:00:10.0880000",
"testResultId": 10631726,
"testResult": {
"result": "Failed",
"detail": "Step 0: No answer within 10 seconds. "
},
"testStepResultList": {
"ringStepResult": {
"step": {
"replyType": "NONE",
"thresholdTime": {
"minor": 5.0,
"major": 10.0
},
"pauseTime": {
"min": 0.0,
"max": 0.0
}
},
"responseTime": "00:00:00",
"duration": "00:00:10.1250000",
"stepResult": {
"result": "Failed",
"detail": "No answer within 10 seconds"
}
},
"callStepResult": []
},
"testCase": {
"callFlow": "Inbound",
"calledNumber": "8002@192.168.11.99",
"preConnectAudio": null,
"testCaseId": 3246,
"name": "API_TC_Manual",
"active": true,
"folderPath": null,
"description": "",
"notes": "",
"modifiedBy": "admin",
"alert": {
"message": "",
"minorThresholdCriticalCount": 3,
"majorThresholdCriticalCount": 1,
"frequency": "Once"
}
},
"dialResult": {
"result": "NoAnswer",
"detail": null
}
}
],
"totalResults": 1,
"returnedResults": 1,
"stepResults": true,
"campaignRun": {
"campaignId": 3093,
"campaignStatus": "Completed",
"campaignName": "Velocity Campaign Created with RestAPI",
"runId": 104884,
"startDate": "2021-11-16T21:44:35.4036169Z",
"endDate": "2021-11-16T21:44:52.0495884Z",
"result": "Success"
}
}