Repository files navigation

Report Bug ·Request Feature ·Ask Question ·Report security bug

This Python library is designed for testing the OData API of Creatio. It includes functionality for authentication, making generic HTTP requests to the OData service, and performing various operations on object collections.

• Authentication: Authenticate and obtain a session cookie for subsequent requests.
• HTTP Requests: Make generic HTTP requests (GET, POST, PATCH, DELETE) to the OData service.
• Collection Operations: Interact with object collections, including adding, modifying, and deleting records.
• Logging: Enable debugging to log detailed information about HTTP requests and responses.

Here's a breakdown of the packages needed and their versions:

• poetry >= 1.7.1 (only for manual installation)
• python-dotenv >= 1.0.1
• requests-cache >= 1.1.1
• requests-pprint >= 1.0.0
• requests >= 2.31.0
• rich >= 13.7.0

creatio-api-py can be installed easily as a PyPI package. Just run the following command:

pip3 install creatio-api-py

pipx install creatio-api-py

If you prefer to install the program manually, follow these steps:

1. Download the latest version ofcreatio-api-py from this repository:

   git clone https://github.com/YisusChrist/creatio-api-pycd creatio-api-py

2. Install the package:

   poetry install --only main

If you installed it from PyPI, you can use the following command:

pipx uninstall creatio-api-py

The package allows you to stablish connection to any Creatio environment using the credentials of a user with the necessary permissions. The following steps will guide you through the process of setting up the environment and running the script.

1. Set up your environment variables by creating a .env file with the following content:

   CREATIO_USERNAME=your_usernameCREATIO_PASSWORD=your_password

2. Authenticate to the Creatio environment:

   fromcreatio_api_py.apiimportCreatioODataAPIfromcreatio_api_py.utilsimportprint_exceptioncreatio_url:str="https://your-environment.creatio.com"api=CreatioODataAPI(base_url=creatio_url)try:# Authenticate with the APIapi.authenticate()exceptExceptionase:print_exception(e,f"Unable to authenticate on{creatio_url}")

   If you don't want to use the .env file, you can pass the credentials directly to theauthenticate method:

   api.authenticate(username="your_username",password="your_password")

   Theauthenticate method will return an HTTP response object. If the status code is 200, the authentication was successful, and the session cookie is stored in theapi object. Therefore, your don't need to pass the cookie to the other methods, it will be used automatically for the next requests.

   However, if you want to check the cookie value, you can access it using thecookie attribute:

   cookie=api.session_cookiesprint(cookie)

   Response Cookie:

   {"BPMLOADER":"lima0ugkfcecqs23bdeio1k4",".ASPXAUTH":"7AE0D4CDCD7DCB01A65ACAF85D8DAC0D842B41745CB17A4AEF4C6F18701757AEA7EAFA90565091E61A54E5559A2B1113C6A6EDA78EFEDECD10176937BBD7F9FEBCAC9210963D42AC059C9858A29F7C903E9CB5FAC3B36CF273B8FF94850CDC01D21F69874990586EEDE392900D87C9D09DF3053D7E5AEDB0D79E0F9172634C9F2566424A5B5F38BD58C2EF1BC06E98ED9168488F7ADE262147E73A3A082CB8CAC74C6A4F6B50555D1ED2A93FC05070E0607B79B32F4ED8B8306918E1F2CCAC1C88CB651DFDF795A36E0A03EFFE0A8AA960BDCD358065C8FDABBF9C59A3FC0B2FEFD77C7E1FC484B6CDAB162F2A5EFB0084FDAA6404AF2773C3DBB8147F83E7040400172E332523BB415AC9432269BF5ED53E2BD70C336CDA513228617AC7A2C9BAD79CBEFE1DE193B1C8E5D6EC836D9F67F4F4033F759CA7E7EDBC433C72441110ECCBD386E05E960822BE049D7BACE51EDFA6B47E57BC654C4B7B3D047AEF9F14F92ACAB37D4286FC9494656B489DE1512DB33869291366E70DA77C9BEDB67706F5896F65B3F835D3C6B4D3367FC7FD086556E1B6F7777FD123848A7038F0AF923758AE398705069FF295D4C0CC180710DC2DE26DD91C09025F0093784241B60757937FEE936A2B80995617DFBB7FE54262F85F7AD4D5465413554A1C67BB0FD21793826C050E8AB83D39747A049C138792E079","BPMCSRF":"ezBoM358i3BgxRyW1kKF0u","UserType":"General","UserName":"83|117|112|101|114|118|105|115|111|114"}

Here are some examples of how to interact with the Creatio API using this package:

fromcreatio_api_py.apiimportCreatioODataAPIfromcreatio_api_py.utilsimportprint_exceptioncreatio_url:str="https://your-environment.creatio.com"api=CreatioODataAPI(base_url=creatio_url)try:# Authenticate with the APIapi.authenticate()exceptExceptionase:# pylint: disable=broad-exceptprint_exception(e,f"Unable to authenticate on{creatio_url}")

• Response code:200 OK
• Response body:

{"Code":0,"Message":"","Exception":null,"PasswordChangeUrl":null,"RedirectUrl":"/0/Shell","UserType":"General"}

payload:dict[str,str]= {"UsrEmail":"test@test.com","UsrTelefono":"123456789","UsrDescripcionBienContratado":"Test",# ... other fields ...}response=api.add_collection_data("Case",data=payload)

• Response code:201 Created
• Response body:

{"@odata.context":"https://your-environment.creatio.com/0/odata/$metadata#Case/$entity","Id":"cf8c6558-9e3e-48ca-a237-765b0f54b798","CreatedOn":"2024-06-17T15:28:32.7013964Z","CreatedById":"410006e1-ca4e-4502-a9ec-e54d922d2c00","ModifiedOn":"2024-06-17T15:28:32.7013964Z","ModifiedById":"410006e1-ca4e-4502-a9ec-e54d922d2c00","ProcessListeners":0,"Number":"SR00005250","UsrDescripcionBienContratado":"Test","UsrEmail":"test@test.com","UsrTelefono":"123456789"// ... other fields ...}

Creatio returns the created record with theId field. You can use this ID to modify or delete the record later.

payload:dict[str,str]= {"UsrDescripcionBienContratado":"New test description",}record_id="cf8c6558-9e3e-48ca-a237-765b0f54b798"response=api.modify_collection_data("Case",record_id=record_id,data=payload)

• Response code:204 No Content
• Response body: None

The response code 204 indicates that the record has been successfully updated. Creatio does not return a body in this case.

record_id="cf8c6558-9e3e-48ca-a237-765b0f54b798"response=api.get_collection_data("Case",record_id=record_id)

• Response code:200 OK
• Response body:

{"@odata.context":"https://your-environment.creatio.com/0/odata/$metadata#Case/$entity","Id":"cf8c6558-9e3e-48ca-a237-765b0f54b798","CreatedOn":"2024-06-17T15:28:32.7013964Z","CreatedById":"410006e1-ca4e-4502-a9ec-e54d922d2c00","ModifiedOn":"2024-06-17T15:28:32.7013964Z","ModifiedById":"410006e1-ca4e-4502-a9ec-e54d922d2c00","ProcessListeners":0,"Number":"SR00005250","UsrDescripcionBienContratado":"New test description","UsrEmail":"test@test.com","UsrTelefono":"123456789",// ... other fields ...}

As you can see, the fieldUsrDescripcionBienContratado has been updated and we have retrieved the last value.

record_id="cf8c6558-9e3e-48ca-a237-765b0f54b798"response=api.delete_collection_data("Case",record_id=record_id)

• Response code:204 No Content
• Response body: None

The response code204 indicates that the record has been successfully deleted. Creatio does not return a body in this case.

If we try to get the record again, we will get a 404 Not Found response:

record_id="cf8c6558-9e3e-48ca-a237-765b0f54b798"response=api.get_collection_data("Case",record_id=record_id)

• Response code:404 Not Found
• Response body: None

It is possible to retrieve information like the total number of requests made, the base url used for the class instance, and the session cookies.

total_requests=api.total_requests# 6base_url=api.base_url# 'https://your-environment.creatio.com'session_cookies=api.session_cookies# {...}

Additionally, you can modify the object's base url if needed:

api.base_url="https://another-environment.creatio.com"

file_id="9dc61894-a14c-dff5-b4ff-6bca9a26018d"api.download_file("ContactFile",file_id=file_id)

• Response code:200 OK
• Response body: The file content

Additionally, you can specify the path where the file will be saved:

file_id="9dc61894-a14c-dff5-b4ff-6bca9a26018d"api.download_file("ContactFile",file_id=file_id,path="path/to/save/file")

Before you participate in our delightful community, please read thecode of conduct.

I'm far from being an expert and suspect there are many ways to improve – if you have ideas on how to make the configuration easier to maintain (and faster), don't hesitate to fork and send pull requests!

We also need people to test out pull requests. So take a look throughthe open issues and help where you can.

SeeContributing Guidelines for more details.

creatio-api-py is licensed under theGNU General Public License v3.0.