Pripravujeme pre Vás novú dokumentáciu, aktuálny stav nájdete tu

CDESK SCRIPT FOR PROCESSING

EMAILS (AZURE VERSION)

Page contents

Overview

This project automates the processing of emails within the CDESK system. It covers fetching new emails, identifying specific actions based on the email content, and performing operations such as creating discussions or requests according to the information obtained.

The script is built as an Azure Function App, as an alternative to the local Dockerised version. Since it runs in the cloud, the application logs cannot be viewed through the local application; instead, they are available in the Azure service. This manual provides a step-by-step guide to creating a Function App using Visual Studio Code. For other methods, if needed, see Microsoft’s official documentation.

This script serves as a demonstration of data processing in CDESK and the automation of object creation – in this case, processing emails and creating requests with a discussion.

Files

function_app.py

The main entry point of the application. The script runs every 5 minutes, initialises the connection to CDESK, fetches new emails, processes each email according to its action code, and logs out once finished.

ConnectionController.py

Handles the connection to the CDESK API. It manages the login process, maintains the session, and performs GET and POST requests with the required authentication.

ObjectController.py

Contains methods for interacting with CDESK objects, such as emails and requests. It includes functions for fetching emails, processing them, and creating discussions or requests based on the email content.

LoggerController.yml

Used to print log messages to the function app logs.

docker-compose.yml

Defines the Docker environment for running the email processing script. It sets up the required environment variables for connecting to CDESK and specifies the network configurations.

last_email_id.txt

A document containing the ID of the last processed email.

Setup and configuration

Creating emails

First, you must have at least one email in Message processing -> Message processing with a certain combination of content.

 

This email should contain a combination of capital letters and numbers, 6 to 8 characters long. This combination can be given either in the subject or the body of the email and will represent the parcel number that the script will process. In addition, the email may contain words about the destination (e.g. Destination: Testovacia 11, Bratislava), which will be added to the newly created request as a custom field.

Example email:

Subject: Dispatch notification NK123455

Body:  Dispatch notification NK123455. Destination: Nová 34, Bratislava. Used for testing purposes only.

Custom field for the request

First, you will need a custom field that the script will use and that will be added to the newly created request when the email is processed. To create a new field, you can follow these steps: 

  1. Create a new test request or open any existing request. 
  2. At the bottom of the request page, click the Add custom fields button.
  3. In the top right corner, click the Simple custom field button.
  4. Fill in the details according to your preferences and click Save.

Required data from CDESK

After creating the custom field, you will need to set the following data from CDESK in the script (as environment variables in the docker-compose.yml file):

  • CDESK_LOGIN – your login name for your CDESK account
  • CDESK_PASSWORD – your password for your CDESK account
  • CDESK_SERVER – your CDESK server (for example, cdeskportal.eu)
  • COMPANY_ID – the ID of the company under which the requests will be created
  • STATUS – the status of the created request (set by default to 10 – „Received“)
  • SOLVER_ID – the ID of the user who will be assigned as the assignee of the request. You can find the assignee ID in the user profile (top right corner in CDESK -> My profile).
  • SLA_ID – the ID of the Service Level Agreement (SLA) record. You can find the SLA ID in the menu or tiles under SLA/SLO -> SLA list.
  • CUSTOM_PROPERTY_ID – the ID of the custom field

    You can find it in the menu / tiles -> Configuration database (or CMDB) -> User-defined fields -> Custom fields.

    Then find the required custom field, open it, and find its ID in the URL address.

Then find the required custom field, open it, and find its ID in the URL address.

  • CUSTOM_PROPERTY_BASEPROPERTY_ID – the baseproperty ID of the custom field

You can find it in the menu / tiles -> Configuration database (or CMDB) -> User-defined fields -> Base properties

  • CUSTOM_PROPERTY_NAME – the name of the custom field (in this example, the default is Target place)
  • TEST – disables certificate checking when sending requests; change only during local testing for security reasons (default False)
  • SCRIPT_NAME – the name of the script that will be used in the logs

Also, to visualise the logs generated by this script, you need to set up a volume mapping to a directory on the local PC or server. This directory can be /logs in the application for logs, which is specifically created for this purpose.

Setup steps
Step 1: Installing the required extensions in Visual Studio Code
  1. Open Visual Studio Code. Go to the Extensions view by clicking the Extensions icon in the Activity Bar on the side, or by pressing Ctrl+Shift+X. 

Search for and install the following extensions:

  • Azure Functions by Microsoft
  • Python by Microsoft
  • Azure Account by Microsoft

Step 2: Logging in to Azure and creating a “remote function app resource”
  1. Go to the Azure tab (Ctrl+Shift+A).
  2. Right-click on Function App -> Create Function App in Azure.
    1. Follow the prompts that will ask you to create the Function App:

    Name: any name for the resource, for example my-email-processing-script

    Runtime stack: If possible, select a newer version of Python, for example Python 3.11.

    Resource location: Select a location that is geographically close to you.

Step 3: Preparing and deploying the local script
  1. In the Azure extension tab in VS Code, click the lightning bolt icon in the workspace to create a function app.
  2. Select the Python interpreter (e.g. 3.11) and cancel the further selection when prompted to choose a function template (press Esc).
  3. Deploy the application via the cloud icon.
Step 4: Setting environment variables in the Azure Portal
  1. Go to https://portal.azure.com/ and find the newly created function app.
  2. In the function app, go to Settings -> Environment variables and add all the environment variables mentioned earlier in this guide.
  3. Your script is ready to run. To view the logs, go up to the Overview tab, where in the Essentials section you will find your application’s trigger (named timer_trigger by default), and click Invocations and more.

Workflow

Note: Cron – This entire script, when dockerised, is set up as a cron that runs every 5 minutes.

  1. Initialisation: The script connects to CDESK via the ConnectionController.
  2. Fetching emails: It retrieves new emails using the ObjectController.
  3. Processing emails: It creates requests or discussions based on the email content.
  4. Termination: The script ends the session with CDESK.

Monitoring and logs

While running, the script generates logs that can be monitored in docker logs. These logs contain initialisation messages, progress updates, and any errors.