Overview

Skill Level: Beginner

Beginner level in python is required

This recipe gives a step-by-step guide of how to create and assign work orders by using IBM Maximo and extract them using API. LexX Intelligence Maintenance Platform consumes work orders to provide integrated data to empower maintenance technicians.

Ingredients

  • IBM Account
  • IBM Maximo
  • Python
  • Event streams service

Step-by-step

  1. Add an asset

    To add an asset to be worked on, click ‘Manage Assets’ button on the welcome page,

     manage_assets1

    Then you will be led to the page below,

    manage_assets3

    Note that you can always go back to the ‘WORK CENTERS’ page by clicking ‘IBM Maximo EAM SaaS’ on your top-left screen,

    manage_assets6

    To add an asset, click ‘Add asset’, then a form will pop up,

    manage_assets4

    You will have to enter required information for this asset. If you are not sure what information should be input, you can check a detailed description by moving pointer/mouse to the ‘i’ icon.

    Then click ‘Add Asset’ button, you can view/edit detailed information about the asset in the following webpage,

    manage_assets5

  2. Create a work order

    To create a work order, click the ‘Work Supervision’ button from ‘work centre’,

    work_supervision1

    Then click the wrench-like button on the bottom right,

    work_supervision2

    Then you can fill up information related to this work order and perform different operations on it, like you can assign a work order by filling up the ‘Owner’ field.

    work_supervision3

    NOTE: You can edit a field by clicking the it, some fields will have to be saved right after being edited, like the ‘Priority’ field.

    work_supervision4

    You can approve a work order by clicking the ‘Approve’ button,

    work_supervision5

    Or you can view and approve work orders on the previous panel,

    work_supervision6

     

  3. Accept/Take a work order

    If you want to manage work order assigned to you, you can view them by clicking ‘Work Execution’ button,

    work_execution1

    You can view the detailed information of work orders by clicking it. Or if you decide to start it, click ‘Start’. If it is started like the left one, you can choose to report it or stop it,

    work_execution2

    You can create a work by clicking ‘Create Work’.

    work_execution3

  4. Extract work orders using REST APIs

    First, administrator needs to give permission to a user who wants to extract work order data. To do this, administrator should add an user: work center -> Administraiton -> People -> Users -> Add User, then follow the instructions to fill up user details. Once it is done, an user profile will appear in the ‘Users’ panel

    extract1

    extract2

    Next, administrator needs to generate a API Key for the user, go to Integration -> API Keys -> Add API key, then choose a user you want give access to. Once it is done, a API key will appear on the ‘API Keys’ panel, you can copy it by clicking ‘Copy Key’ and send it to the user.

    extract3

    From users’ side, once you get the API Key from administrator, you can access data like work orders, assets, etc by sending a request to a server. Either you can create your own URL for the request or you can use a scripting tool to help you, the following script in python demonstrates the later.

    '''----------------------------------Python code-------------------------------------------'''
    import requests

    API_KEY = '<YOUR_API_KEY>'

    OBJECT_STRUCTURE = 'mxapiwo'
    url = 'https://trial.maximosaas.ibm.com/maximo/api/os/'+OBJECT_STRUCTURES
    SELECT = 'estdur'

    params = {"lean": '1', 'apikey': API_KEY, 'oslc.select': SELECT}
    response = requests.get(url=url, params=params)
    print(response.text)
    '''----------------------------------Python code-------------------------------------------'''

    In the code above, what data will be retrieved depends on the ‘OBJECT_STRUCTURE’ and the ‘SELECT’ variable. You can change the OBJECT_STRUCTURE variable to other values to access other types of data. For example, to access assets data, you need to change it to ‘mxapiasset’. SELECT determines what fields of data you want to retrieve. For example, in a work order, field ‘estdur’ represents duration of the work order. All fields will be returned if its value is ‘*’. To get the full list of predefined values for ‘OBJECT_STRUCTURE’ and ‘SELECT’, please refer to the API documents: Integration -> API Keys, click the arrow button on the top-right corner, click API documentation.

    extract4

     

  5. Configure notification/event streams

    The following steps will introduce how users can get notifications about the update of work orders.

    To get this feature running, we need to configure the IBM event streams service first.

    Make sure you are able to find credentials for IBM event streams service you subscribed, they can be found on your IBM CLOUD panel,

    Launch your IBM Cloud -> Services -> Event Streams-ls -> Service Credentials -> View credentials,

    event1

    Then, Then a topic to be bound with an event is needed. To create a topic, Go to ‘Manage’ -> Topics -> ‘Create topic’

    Or leave this step first, when a kafka console is created later, it will automatically create a topic.

    NOTE: this may charge additional fee.

    event3

    Then time to set up an event,

    Launch Maximo -> Administration -> Integration -> Outbound Events -> Add event

    It requires some information like which OBJECT_STRUCTURE you want your event listen to, and the topic you created.

    NOTE: when you access to the ‘Outbound Events’ for the first time, you will be asked for your event stream service information i.e. your credentials for event streams. Just copy and paste they to the corresponding field.

    event4

    Once an event is created, you will see it on the panel above. Click ‘Activate event’.

    Now, your event stream is up and running! It will automatically detect any changes users have made on OBJECT_STRUCTURE and send notifications. To get notifications sent by event stream, you will need to run a special server called kafka-console. There are different kafka-console written in different programming languages, choose one you prefer. Here, we will use kafka-python-console.

    Go to https://github.com/ibm-messaging/event-streams-samples -> clone or download the repository -> follow the instructions given in ‘README’ file to run the console.

    Then you’ll see the console will receive and display notifications from the event stream you just configured,

    event5

    Let the console run in the background, go to Maximo and update the corresponding object(like a work order) which is monitored by event streams. Then a notification about the update will show up in the console.

    event6

    NOTE: for the kafka-python-console, it may be shut down and throw an exception. If this happens in your case,

    Go to the console folder -> open ‘consumertask.py’ with a text editor -> replace line 38-44 with the following code

    '''-----------------------------------python code------------------------------------------'''

    if msg is not None and msg.error() is None:
    print('Message consumed: topic={0}, partition={1}, offset={2}, value={3}'.format(
    msg.topic(),
    msg.partition(),
    msg.offset(),
    msg.value().decode('utf-8')))

    '''-----------------------------------python code------------------------------------------'''

     

Join The Discussion