Functional Setup Manager (FSM) has many capabilities. One that can be very powerful is the ability to use REST APIs to drive the import and export of Tasks or Offerings in CSV format.
In this blog we examine using these API calls to import and export Fast Formula.
A quick overview
FSM REST APIs support import and export of business object setup data at a Task or Offering level. Since we’re focused on migrating a single business object, we’ll be using the Task versus Offering APIs. You can find these APIs documented here:
https://docs.oracle.com/en/cloud/saas/applications-common/23a/farca/api-setup-task-csv-exports.html
First you’ll see how to export all Fast Formula using the Task API SetupTaskCSVExportProcess to create an export process. You will then see how to use scope to limit to a single formula using the API setupTaskCSVExports and specifying a criteria in the JSON payload.
To start, make an API call to initiate a Task CSV Export process. Once that process has completed, you then make another call to download the data. To import into a different environment, you upload that data along with a call to start an import process.
Setting up the Export
To do the export you’ll be using the SetupTaskCSVExportProcess resource in the REST API. This will create and initiate a job that generates an export package of all Fast Formula.
First, though, trigger an export via the FSM UI and download the generated CSV File Package which is a zip file. You can then take a look at the generated content to get some crucial info.
If you open the generated zip file you will see CSV files representing the Fast Formula objects, and a metadata file that contains details about the export process and contents of this CSV File Package. Extract and open the metadata file (ASM_SETUP_CSV_METADATA.xml) and look for ObjectShortName which represents the business object selected for export. In this case you will see PAY_MANAGE_FAST_FORMULA. This is the TaskCode you pass in the API call to start the export process.
To start the export, call the SetupTaskCSVExportProcess API using the POST method and passing as the JSON parameter the task code:
https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVExports/PAY_MANAGE_FAST_FORMULA/child/SetupTaskCSVExportProcess
{
"TaskCode": "PAY_MANAGE_FAST_FORMULA"
}
This will trigger a system process to do the export, and the return will indicate the ProcessId, which you will need to retrieve the file contents. Here is the response:
{
"ProcessId": 100001386122514,
"TaskCode": "PAY_MANAGE_FAST_FORMULA",
"ProcessCompletedFlag": null,
"links": [
{
"rel": "self",
"href": "https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVExports/PAY_MANAGE_FAST_FORMULA/child/SetupTaskCSVExportProcess/100001386122514",
"name": "SetupTaskCSVExportProcess",
"kind": "item"
},
{
"rel": "canonical",
"href": "https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVExports/PAY_MANAGE_FAST_FORMULA/child/SetupTaskCSVExportProcess/100001386122514",
"name": "SetupTaskCSVExportProcess",
"kind": "item"
},
{
"rel": "parent",
"href": "https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVExports/PAY_MANAGE_FAST_FORMULA",
"name": "setupTaskCSVExports",
"kind": "item"
},
{
"rel": "child",
"href": "https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVExports/PAY_MANAGE_FAST_FORMULA/child/SetupTaskCSVExportProcess/100001386122514/child/SetupTaskCSVExportProcessResult",
"name": "SetupTaskCSVExportProcessResult",
"kind": "collection"
}
]
}
Before retrieving the file contents, you must ensure the process has completed. To do this use the GET REST API SetupTaskCSVExportProcess with the ProcessId to poll the completion status of the process:
https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVExports/PAY_MANAGE_FAST_FORMULA/child/SetupTaskCSVExportProcess/100001386122514
Here is the response:
{
"ProcessId": 100001386122514,
"TaskCode": null,
"ProcessCompletedFlag": true,
"links": [
{
"rel": "self",
"href": "https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVExports/PAY_MANAGE_FAST_FORMULA/child/SetupTaskCSVExportProcess/100001386122514",
"name": "SetupTaskCSVExportProcess",
"kind": "item"
},
{
"rel": "canonical",
"href": "https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVExports/PAY_MANAGE_FAST_FORMULA/child/SetupTaskCSVExportProcess/10 0001386122514",
"name": "SetupTaskCSVExportProcess",
"kind": "item"
},
{
"rel": "parent",
"href": "https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVExports/PAY_MANAGE_FAST_FORMULA",
"name": "setupTaskCSVExports",
"kind": "item"
},
{
"rel": "child",
"href": "https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVExports/PAY_MANAGE_FAST_FORMULA/child/SetupTaskCSVExportProcess/100001386122514/child/SetupTaskCSVExportProcessResult",
"name": "SetupTaskCSVExportProcessResult",
"kind": "collection"
}
]
}
Retrieving the data
Once the process has completed, you can call the next API to retrieve the file contents. Make a GET call to SetupTaskCSVExportProcessResult to retrieve FileContent from the process.
https://myserver/fscmRestApi/resources/latest/setupTaskCSVExports/PAY_MANAGE_FAST_FORMULA/child/SetupTaskCSVExportProcess/100001386122514/child/SetupTaskCSVExportProcessResult/100001386122514/enclosure/FileContent
The result will be returned in binary format.
<data contentType="application/octet-stream" contentLength="2683474">binary data==</data>
When saved to a file this will be a .zip formatted file that can then be opened by any zip manager.
Importing the data
To import this data to a different environment you take the data, BASE64 encode it and add it to the JSON payload of the import REST call along with the task code info:
https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVImports
{
"TaskCode" : "PAY_MANAGE_FAST_FORMULA",
"SetupTaskCSVImportProcess" : [{ "TaskCode" : "PAY_MANAGE_FAST_FORMULA",
"FileContent": "Base64 encoded data"}]
}
You’ll be able to check the status of the import by querying the Import Process Result in the same way as you checked the Export Process Result above.
After that process completes, download the data and upload just as described above.
Using Scope to select a single Fast Formula
To restrict the export to a single fast formula, you will need to use a slightly different API setupTaskCSVExports,
With this API you can include criteria for the process to export. This will be set in the RequestBody JSON payload similar to the following:
https://myserver/fscmRestApi/resources/11.13.18.05/setupTaskCSVExports
{
"TaskCode" : "PAY_MANAGE_FAST_FORMULA",
"SetupTaskCSVExportCriteria" : [
{ "TaskCode" :"PAY_MANAGE_FAST_FORMULA" ,
"BusinessObjectCode": "FF_FORMULA",
"AttributeName" : "FormulaId",
"AttributeValue" : " 300000014097106" }
],
"SetupTaskCSVExportProcess" : [{ "TaskCode" : "PAY_MANAGE_FAST_FORMULA" }]
}
Generally by examining the results of an export with scope via the UI, you can determine the correct values for BusinessObjectCode, AttributeName and AttributeValue. For details, see Apply Scope to Filter Exported Setup Data in the document https://docs.oracle.com/en/cloud/saas/applications-common/23a/oafsm/automate-export-and-import-of-csv-file-packages.html#s20068206
However, setting scope for Fast Formula is a little different from the method described in that document. You need to pass the ID of the formula in scope rather than the formula name. You can retrieve the ID by the SQL
select formula_id from ff_formulas_b_f where base_formula_name=upper('MyFastFormula');
Compiling Fast Formula
There is also the capability to compile fast formula by using a SOAP API. This utilizes the FlowActionService, SubmitFlow API which is documented here:
The Service WSDL can be found by this pattern: https://myserver/hcmService/FlowActionsService?WSDL
You will call the submitFlow endpoint with the Compile Formula flow name, and as the Formula ParameterValue either give the formula name or use % as a wildcard to compile all formulas.
Here is an example using basic authentication and compiling all formula; use a specific formula name in the Formula ParameterValue to trigger compilation for a single formula only. You also should be able to construct a WS-Security header instead of using Basic auth.
POST https://myserver.mydomain.com:443/hcmService/FlowActionsService HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://xmlns.oracle.com/apps/hcm/processFlows/core/flowActionsService/submitFlow"
Authorization: Basic xxxxx
Content-Length: 1270
Host: myserver.mydomain.com:443
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:typ="http://xmlns.oracle.com/apps/hcm/processFlows/core/flowActionsService/types/" xmlns:flow="http://xmlns.oracle.com/apps/hcm/processFlows/core/flowControllerService/">
<soapenv:Header/>
<soapenv:Body>
<typ:submitFlow>
<typ:flowName>Compile Formula</typ:flowName>
<typ:parameterValues>
<flow:ParameterName>Formula</flow:ParameterName>
<flow:ParameterValue>%</flow:ParameterValue>
</typ:parameterValues>
<typ:parameterValues>
<flow:ParameterName>Formula Type</flow:ParameterName>
<flow:ParameterValue>%</flow:ParameterValue>
</typ:parameterValues>
<typ:flowInstanceName>Compile Formula blogtest</typ:flowInstanceName>
<typ:legislativeDataGroupName>US Legislative Data Group</typ:legislativeDataGroupName>
<typ:recurringFlag>false</typ:recurringFlag>
</typ:submitFlow>
</soapenv:Body>
</soapenv:Envelope>
In this article you’ve seen how to use the FSM REST APIs to create an export process to export Fast Formulas and to check the status of that process. You’ve then called another API to download the contents for saving to a file. You also saw how to pass a scope parameter to filter the results of the export. Next you saw how to take the file contents and pass to another REST API to initiate an import process. Finally, you were introduced to another API that can trigger the compilation of Fast Formulas.
The FSM REST APIs are a powerful set of APIs that can be used to programatically import and export many different business objects and groups of business objects.