How do I use the search API?

The following examples help you get started with the IBM Blueworks Live search API.

The examples are based on the following space hierarchy:

Grandparent Space
-Grandparent Process
-Parent Space
--Parent Process # linked to "Linked Process"
--Child Space
---Child Process
Linked Space
-Linked Process

Searching for a space by name

Searching for a space returns all child spaces and all the processes in the child spaces. If an activity is linked to a process in another space, the linked process is referenced but not returned.

For example, if you search using the following parameters:

searchValue=Grandparent Space
searchFieldName=space_name

You see the following results:

{
 "spaces": [
   {
     "id": "2737002c",
     "name": "Grandparent Space",
     "processes": [
       {
         "id": "27370032",
         "milestones": [...], # Everything in the process is returned.
         "name": "Grandparent Process"
       }
     ]
   },
   {
     "id": "27260049",
     "name": "Parent Space",
     "parentSpaceId": "2737002c",
     "processes": [
       {
         "id": "2726004f",
         "milestones": [...],  # Everything in the process is returned. If an activity is linked to a process in another space, it has a "linkedProcessId" property.
         "name": "Parent Process"
       }
     ]
   },
   {
     "id": "27260002",
     "name": "Child Space",
     "parentSpaceId": "27260049",
     "processes": [
       {
         "id": "27260008",
         "milestones": [...],  # Everything in the process is returned.
         "name": "Child Process"
       }
     ]
   }
 ]
}

If you search for a space that has no child spaces, only that space and its processes are returned. For example, if you search using the following parameters:

searchValue=Child Space
searchFieldName=space_name

You see the following results:

{
 "spaces": [
   {
     "id": "27260002",
     "name": "Child Space",
     "parentSpaceId": "27260049",
     "processes": [
       {
         "id": "27260008",
         "milestones": [...], # Everything in the process is returned.
         "name": "Child Process"
       }
     ]
   }
 ]
}

Searching for a process by name

Searching for a process returns its direct parent space.

For example, if you search using the following parameters:

searchValue=Parent Process
searchFieldName=process_name

You see the following results:

{
 "spaces": [
   {
     "id": "27260049",
     "name": "Parent Space",
     "processes": [
       {
         "id": "2726004f",
         "milestones": [...],  # Everything in the process is returned. If an activity is linked to a process in another space, it has a "linkedProcessId" property.
         "name": "Parent Process"
       }
     ]
   }
 ]
}

If you search using the following parameters:

searchValue=Grandparent Process
searchFieldName=process_name

You see the following results:

{
 "spaces": [
   {
     "id": "2737002c",
     "name": "Grandparent Space",
     "processes": [
       {
         "id": "27370032",
         "milestones": [...],  # Everything in the process is returned.
         "name": "Grandparent Process"
       }
     ]
   }
 ]
}

Searching for a property

The following example shows a search for a property, in this case an input on a milestone. Only the activity milestone is returned, with the direct parent process and the direct parent space.

If you search using the following parameters:

searchValue=Parent process input
searchFieldName=input

You see the following results:

{
 "spaces": [
   {
     "id": "27260049",
     "name": "Parent Space",
     "processes": [
       {
         "id": "2726004f",
         "milestones": [
           {
             "business owners": [
               {
                 "id": "27373507",
                 "name": "parent process business owner"
               }
             ],
             "id": "27260053",
             "inputs": [
               {
                 "id": "27372d07",
                 "name": "Parent process input"
               }
             ],
             "name": "Milestone 1"
           }
         ],
         "name": "Parent Process"
       }
     ]
   }
 ]
}

The following example shows a search for an input on an activity with a linked process. The linked process is referenced but not returned.

If you search using the following parameters:

searchValue=Parent process input on linked activity
searchFieldName=input

You see the following results:

{
 "spaces": [
   {
     "id": "27260049",
     "name": "Parent Space",
     "processes": [
       {
         "id": "2726004f",
         "milestones": [
           {
             "activities": [
               {
                 "business owners": [
                   {
                     "id": "27374202",
                     "name": "Parent process business owner on linked activity"
                   }
                 ],
                 "id": "27260057",
                 "inputs": [
                   {
                     "id": "27372d11",
                     "name": "Parent process input on linked activity"
                   }
                 ],
                 "linkedProcessId": "27370070",
                 "name": "Activity",
               }
             ],
             "id": "27260053",
             "name": "Milestone 1"
           }
         ],
         "name": "Parent Process"
       }
     ]
   }
 ]
}

For the API documentation, see Search.