1.     Introduction to Integration with Git

Git repositories can now be used to store PA objects in a standard JSON format. Since PA also allows to pull the changes from this JSON format, you can now use a Git repository to migrate changes from one environment (e.g. Dev) to another (e.g. Prod).

Also, since the JSON format is well described and standard, you can potentially create applications to update a TM1/PA server objects in real time using PA ReST API and Git integration.

PA provides a set of ReST API functions to interact with Git. However, before you could connect to Git there are few things that you need to do. This guide provides step by step instructions to setup and then connect to a Git repository.

The guide uses Github, but the steps could be used for any other Git provider.

 

2.     Create a new Git Repository

You can go to github.com, sign-up/sign-in, and then create a new Git repository that you want to use for storing TM1 object sources. Once you’ve created the repository, keep the repo URL. We’d use it in next steps.

 

3.     Export Git Server Certificate

Open the github.com (or any other git provider that you want to use) in a browser window.

When you click on the certificate option, the certificate will be opened in a new window.

The certificate window will show total 3 certificates.

You need to import all 3.

Click on the first one, then click on View certificate button below, and export it.

Similarly, click on the second one, and then export it to a file. You can export the third one (github.com) from the “first” window that you had opened.

Exporting 3 files will give you 3 (*.cer) files that you need to import into PA certificate store.

 

4.     Import Git Server Certificates

Copy the 3 certificate files that you exported into the following directory:

C:\Program Files\ibm\cognos\tm1_64\bin64\ssl

NOTE: You don’t necessarily need to copy the certificates to this directory specifically, you can choose any other directory, just remember to use the corresponding path in the certificate import command.

Launch command prompt in the administrator mode and run following commands to import the certificates:

• "C:\Program Files\ibm\cognos\tm1_64\bin64\gsk8capicmd_64.exe"

-cert -add -db "C:\Program Files\ibm\cognos\tm1_64\bin64\ssl\ibmtm1.kdb"

-file "C:\Program Files\ibm\cognos\tm1_64\bin64\ssl\github.cer"

-label github -stashed -format ascii -trust enable

• "C:\Program Files\ibm\cognos\tm1_64\bin64\gsk8capicmd_64.exe"

-cert -add -db "C:\Program Files\ibm\cognos\tm1_64\bin64\ssl\ibmtm1.kdb"

-file "C:\Program Files\ibm\cognos\tm1_64\bin64\ssl\git2.cer"

-label github2 -stashed -format ascii -trust enable

• "C:\Program Files\ibm\cognos\tm1_64\bin64\gsk8capicmd_64.exe"

-cert -add -db "C:\Program Files\ibm\cognos\tm1_64\bin64\ssl\ibmtm1.kdb"

-file "C:\Program Files\ibm\cognos\tm1_64\bin64\ssl\git3.cer"

-label github3 -stashed -format ascii -trust enable

 

NOTE:

• Provide the correct path of gsk8capicmd_64 file.
• Provide the correct certificate store file path.
• Remember the file will be in a different (probably in bin) folder for 32-bit version.
• Verify the correct path to the certificates you exported.
• Provide the correct certificate file names.
• The above commands have been shown in few different lines for legibility, you’d have to put your commands in one line.

If you ran the command correctly, it should finish without any message.

Sample output:

5.     Initiate Remote Git

Before you could commit the changes to a git repository, you need to connect/bind your PA model to it. For doing so, you need to run a GitInit call on your PA model and provide the remote Git details. On running this command, a new control directory }git is created in your data folder.

Open Postman and hit following URL:

POST https://<server_ip>:<http_port>/api/v1/GitInit

{

“URL”: “<repository URL>”,

“Deployment”: “dev”,

“Username”: “<provide your username>”,

“Password”: “<provide your password>”,

“Force”: true

}

See sample below:

NOTE: In the sample screenshot above, the real username and password have been removed.

If the command ran successfully, you should see the HTTP return status 201 Created

6.     Push Objects to Git

6.1        Stash the changes

Make following ReST call to push objects to the repository:

POST https://<server_ip>:<http_port>/api/v1/GitPush

{

“NewBranch”: “Monthly_Hierarchy_Changes”,

“Force”: “true”,

“Message”: “Updated entity and product dimensions”,

“Author”: “Rahul”,

“Email”: “admin@abcd.com”

}

 

If the call ran successfully, you’d see the HTTP return status as 201 Created. In the response JSON, note down the ID returned, we’d need to use it in our next API call.

6.2        Commit the changes to Git

Now execute the GitExecute ReST call to push the changes to your remote git repository.

If the call ran successfully, you should receive 204 No Content HTTP status message.

On successful execution, you can verify that your empty git now has files:

7.     Pull Objects from Git

Before you could pull the changes into a different target PA application model, you need to do a GitInit on that model as well.

So, execute the GitInit:

POST https://<server_ip_2>:<http_port_2>/api/v1/GitInit

{

“URL”: “<repository URL>”,

“Deployment”: “dev”,

“Username”: “<provide your username>”,

“Password”: “<provide your password>”,

“Force”: true

}

 

Remember that server IP and http port will be of the target PA server.

Running this call binds the target server with the same Git repository. So now we can pull the changes from it.

7.1        Create a Git Pull Plan

Run following ReST call to create a pull plan on the target.

POST https://<server_ip_2:<http_port_2>/api/v1/GitPull

{

“Branch”: “Monthly_Hierarchy_Changes”,

“ExecutionMode”: “SingleCommit”,

“Force”: “true”,

“Username”: “<git username>”,

“Password”: “<git password>”

}

Remember that the branch should be the branch from which we want to pull the changes. In our case, we want to pull Monthly_Hierarchy_Changes since that’s the branch we pushed our dimension changes to.

The call will return a pull plan ID that we’d need to use in our next call to execute the plan.

7.2        Execute the Git Pull Plan

POST https://<server_ip>:<http_port>/api/v1/GitPlans(’42fg0YCCYyI=’)/tm1.Execute

{

“Branch”: “Monthly_Hierarchy_Changes”,

“ExecutionMode”: “SingleCommit”,

“Force”: “true”,

“Username”: “<git username>”,

“Password”: “<git password>”

}

The successful completion of ReST call will return 204 No Content status.

After completion of this call you can verify the objects in the data directory or using IBM TM1 Architect etc.

8.     Detach Git from PA Server

You can use UnInit ReST call to detach the Git repository from PA server. Doing so will remove the control }Git folder and disable all other Git related functions except GitInit.

9.     Important Links

TM1 Git Integration IBM Documentation

GitHub.com

 

Keywords: PA/TM1 Git Integration, Migrate PA dev to prod using Git, TM1 API ReST calls for Git Integration, TM1 and Git

 

This post has been written by our Guest Writer Rahul Parashar from IBM