Getting Started: Creating and Working with Journals, Tickets, and Follow-Ups

Prerequisites

This guide assumes familiarity with the following:

• Obtaining a security token to access CostGuard web services
• Querying ODatas

Introduction and Basic Terminology

While CostGuard users work with journals, tickets, and follow-ups in the Tickets web and CostGuard client applications, each of these are actually Journal objects (plain or specialized), hence we’ll be working with the Journals API throughout this guide.

Tickets (a.k.a. Trouble Tickets) track problems and resolutions, either for pieces of equipment, individual customers, or multiple customers (the latter referred to as Global Tickets.) Tickets have their own lifecycle, and may be tied to a CostGuard workflow. Tickets may also be nested in a parent/child hierarchy. They may also be placed on hold and later resumed, stopping the clock so as to not count against SLAs when waiting, for example, as customer or vendor response.

Follow-Ups are actionable items with their own lifecycle. They may be added directly to a customer account or to any ticket.

Journals are used to store notes and other miscellaneous information on a customer account. Journals may be added directly to customer accounts, or may be added to specific trouble tickets or to follow-ups.

Journal Item is the generic base term for Journals, Follow-Ups, and Tickets.

DISCLAIMER: The included code snippets are only meant to serve as pseudo code and are not intended to be compilable as is. For more specific code examples, please refer to the sample project.

Creating Journal Items

Basic structure of a Create Journal API Request

The following C# snippet is the basic outline for the creation of journals, follow-ups, and tickets. Note the use of the CreateJournalItemReq, CreateJournalItemRequest, and CreateJournalItemResponse container objects.

//Obtain a requestor object (see the IDI Authentication user guide)
Requestor requestor = new Requestor();

//Obtain a security token 
Context context = await SimpleWebTokenAccess.CreateSWT();

//Create a Channel object for the Journal web service using the appropriate endpoint address.
ChannelFactory factory = new ChannelFactory("JournalServicePort", endpointAddress);
JournalServicePortTypeChannel channel = factory.CreateChannel();
requestor.AuthorizationToken = "AuthorizationToken";

//Populate the request details
//When creating Journals, Follow-ups, or Tickets, the request type is always CreateJournalItemReq

CreateJournalItemReq req = new CreateJournalItemReq()
{
	CreateJournalItem = new CreateJournal()
	//CreateFollowUp = new CreateFollowUp()
	//CreateTicket = new CreateTicket()
	{
		// Required and Optional Properties
		// See specific examples of creation objects in the Common Tasks section
	}
};

//Create a request wrapper
CreateJournalItemRequest request = new CreateJournalItemRequest(requestor, req);

//submit the request
CreateJournalItemResponse response = channel.CreateJournalItem(request);

//Error handling
if (response.Messages != null)
{
	Console.WriteLine("The following errors have occurred:");
	foreach (var msg in response.Messages)
	{
		Console.WriteLine(msg.MessageMember);
	}
}
else
{
	Console.WriteLine("New JournalItemID: " + response.Result.JournalItem.JournalItemID)
	Console.WriteLine("No errors occurred.");
}

Common Required Properties

Whether using CreateJournal(), CreateFollowUp(), or CreateTicket(), this property is required:

• JournalItemTypeID – JournalItemTypeID OData for valid values specific to Journals, Follow-Ups, and Tickets

Other Common Properties

• Description
  • For a journal, the Description is effectively the journal entry
  • For follow-ups and tickets, this is the full writeup
    • Tickets have a separate Title property (covered later) that serve as a short version of the Description
  • Description is required for Tickets; for Journals and Follow-Ups, if not supplied, the Description will default to the Journal Type name
• IsInternal – Internal journals are not exposed to OnlineBill customers. Defaults to False if not specified.
• IsRetained – Exposes the journal/follow-up/tickets in the Customer Summary view (CostGuard Client) and InfoCenter (Tickets Web App). Defaults to False if not specified.
• JournalItemStatusID
  • Required for Tickets, but optional/informational for Journals and Follow-Ups
  • See JournalItemStatusID OData for valid values
• ObjectType & ObjectID – see table

ObjectType enum	ObjectID
Customer	The CustomerID of the customer to which the journal/ticket/follow-up is being added
BillingOrder	Any system OrderID (carts in the older Ordering module)
Equipment	The EquipmentID of the inventory item to which the journal/ticket/follow-up is being added
JournalItem	If adding a journal to a follow-up, the Follow-up ID. If adding a journal or follow-up to a Ticket, the TicketID. If adding a child trouble ticket, the TicketID of the parent ticket.

Creating Journal Items

Creating a Journal

This example creates a simple journal on the customer’s record. Because IsRetained is set to True, this journal would show in the Customer Summary and InfoCenter areas of the CostGuard Client/Tickets web module.

CreateJournalItem = new CreateJournal()
{
	Description  = "This is an excellent customer journal",
	IsRetained = true, // Displays in InfoCenter
	JournalItemTypeID = 1013 // Type must be of Journal Class "Journal"
	ObjectID = 1407, // Assumes CustomerID 1407 exists in Core database
	ObjectType = ObjectType.CustomerID
}

Creating a Follow-Up

This example creates a follow-up for an existing order. Two more properties are required when creating follow-ups:

• ActionDate – When action should be taken by the analyst for the follow-up
• AssignedUser – Initial user responsible for the follow-up. Note this does not have to be an existing CostGuard user account, though the GUIs may enforce your end users to change it to one eventually.

CreateJournalItem = new CreateFollowUp()
{
	ActionDate = DateTime.Now.AddDays(3), //Follow-Up date in the GUI
	AssignedUser = "APITest",
	Description  = "Remind customer of 4Q End discount",
	JournalItemTypeID = 1002 // Type must be of Journal Class "Follow-Up"
	ObjectID = 10516, // OrderID
	ObjectType = ObjectType.BillingOrder
}

Adding a Journal to a Follow-Up

Building off the last two examples, here is how to add a journal to the follow-up:

CreateJournalItem = new CreateJournal()
{
	Description  = "This is a REALLY good deal",
	JournalItemTypeID = 1013, // Type must be of Journal Class "Journal"
	ObjectID = 197, // Captured/looked-up JournalItemID of the follow-up created above
	ObjectType = ObjectType.JournalItem
}

Creating a Ticket

Creating a ticket requires the same properties to be supplied as for follow-ups, plus:

• PriorityID – See TicketPriority OData for valid values
• TicketClass – see table

TicketClass enum	Description
Customer	Customer-related issue
Email	Unsolicited, or “cold” communications; when configured along
Equipment	Equipment-related issue
StandAlone	Not global, not tied to any other entity in particular (included for legacy CostGuard compatibility)
Global	Affects all customers and equipment

Here is an example of creating a customer-assigned ticket:

CreateJournalItem = new CreateTicket()
{
	ActionDate = DateTime.Now.AddDays(3), //Follow-Up date in the GUI
	AssignedUser = "APITester",
	Description = "Customer is missing some megahertz",
	JournalItemTypeID = 4, // Type must be of Journal Class "Ticket"    
	ObjectID = 1407,
	ObjectType = ObjectType.Customer,
	PriorityID = 1,
	TicketClass = TicketClass.Customer
}

And an example of creating a global ticket:

CreateJournalItem = new CreateTicket()
{
	ActionDate = DateTime.Now.AddDays(3), //Follow-Up date in the GUI
	AssignedUser = "APITester",
	Description = "All customers are missing gigahertz!!",
	JournalItemTypeID = 4, // Type must be of Journal Class "Ticket"    
	PriorityID = 1,
	TicketClass = TicketClass.Global
}

Editing Journal Items

Basic structure of a Modify Journal API Request

Below is the outline for editing journal items; it is essentially the same structure as in the Create examples from earlier, except it uses the ModifyJournalItemReq, ModifyJournalItemRequest, and ModifyJournalItemResponse container objects.

//Obtain a security token Context context = await SimpleWebTokenAccess.CreateSWT(); //Create a Channel object for the Journal web service using the appropriate endpoint address.
ChannelFactory factory = new ChannelFactory("JournalServicePort", endpointAddress);
JournalServicePortTypeChannel channel = factory.CreateChannel(); 

Requestor requestor = new Requestor();
requestor.AuthorizationToken = "AuthorizationToken";

ModifyJournalItemReq req = new ModifyJournalItemReq()
{
	myJournalItem = new JournalServiceReference1.JournalItem
	//myFollowUp = new JouranlServiceReference1.FollowUp
	//myTicket = new JournalServiceReference1.Ticket
	{
		// Required and Optional Properties
		// See specific examples of modify objects in the Common Tasks section
	}
};

ModifyJournalItemRequest request = new ModifyJournalItemRequest(requestor, req);
ModifyJournalItemResponse response = channel.ModifyJournalItem(request);

if (response.Messages != null)
{
	Console.WriteLine("The following errors have occurred:");
	foreach (var msg in response.Messages)
	{
		Console.WriteLine(msg.MessageMember);
	}
}
else
{
	Console.WriteLine("No errors occurred.");
}

Editing a Journal

To edit a journal simply requires the JournalItemID of the journal, plus any desired property updates. Unspecified properties will be left alone upon edit.

JournalItem = new JournalServiceReference1.JournalItem
{
	Description = "Check in after New Year’s.",
	JournalItemID = 198
}

Editing a Follow-Up

Modifying follow-ups are a similar prospect.

JournalItem = new JournalServiceReference1.FollowUp
{
	ActionDate = Convert.ToDateTime("1/2/2018"),
	Description = "Check in after New Year’s.",
	JournalItemID = 199
}

Editing a Ticket

This ticket edit example illustrates setting new informational properties, ReferenceNumber and TrackingNumber.

JournalItem = new JournalServiceReference1.Ticket
{
	JournalItemID = 203,
	ReferenceNumber = "ABC123",
	TrackingNumber = "XYZ789",
}

Deleting Journal Items

Basic structure of a Delete Journal API Request

Deleting Journal Items also uses the ModifyJournalItem container objects. Setting the appropriate Journal Item class and JournalItemID is done in the same manner as with Edits; the key difference is the Remove property that gets set to true on the ModifyJournalItemReq object.

Deleting a Journal

ModifyJournalItemReq req = new ModifyJournalItemReq()
{
	JournalItem = new JournalServiceReference1.Journal
	{
		JournalItemID = 200
	}
};
req.Remove = true;

Deleting a Follow-Up

ModifyJournalItemReq req = new ModifyJournalItemReq()
{
	JournalItem = new JournalServiceReference1.FollowUp
	{
		JournalItemID = 201
	}
};
req.Remove = true;

Deleting a Ticket

ModifyJournalItemReq req = new ModifyJournalItemReq()
{
	JournalItem = new JournalServiceReference1.Ticket
	{
		JournalItemID = 202
	}
};
req.Remove = true;

Additional Ticket-specific Operations

Updating a Ticket’s Status

JournalItem = new JournalServiceReference1.Ticket
{
	JournalItemID = 202,
	JournalItemStatusID = "1002"
}

Placing a Ticket On Hold

Setting any HoldReasonID property (see the TicketHoldReason Odata for valid values) will place the ticket “On Hold”. (This is also referred to as “parking” the ticket.)

JournalItem = new JournalServiceReference1.Ticket
{
	JournalItemID = 206,
	HoldReasonID = "1" //id as string;  Waiting on Customer action
}

Resuming an On Hold Ticket

Resume the On Hold ticket by setting the HoldReasonID to any empty string.

JournalItem = new JournalServiceReference1.Ticket
{
	JournalItemID = 206,
	HoldReasonID = "" //clear the On Hold status by setting to empty string
}

Closing a Ticket

Closing a ticket (after which no modifications may be made to it) involves setting the Close property to true. Setting the JournalItemStatusID, ResolutionTypeID, ResolutionNote at this time is also recommended. See the TicketResolutionType Odata for possible values.

JournalItem = new JournalServiceReference1.Ticket
{
	Close = true,
	JournalItemID = 202,
	JournalItemStatusID = "1005", //may differ per system, as custom statuses allowed
	ResolutionNote = "All's well that ends well.",
	ResolutionTypeID = "10001" //int as string
}

Assigning a Customer to a Ticket after the fact

The Email Ticket Class is useful for tracking unsolicited, or “cold” emails in the CostGuard system. If the contact later becomes a customer (or it is later realized that the email address from which the ticket was created belongs to an existing customer), simply assign the ticket to the customer with the ObjectID and ObjectType as before in the Create examples.

JournalItem = new JournalServiceReference1.Ticket
{
	JournalItemID = 207,
	ObjectID = 1407,
	ObjectType = ObjectType.Customer
}

Miscellaneous Points

Some extra pointers and things to be aware of.

Nullable Types

The nullable types in the service definition may be submitted as those types for the CreateJournal methods, however some of these properties you may see are of type <IntString> (an IDI custom type) when submitting Modify requests, and will need to be cast as strings.

An example of this is the non-required JournalItemStatusID property. On a Modify:

• if set to null then the WS will treat it like no change
• if you want to clear the status you would send an empty string
• if you want to set it to another value you would send the int value in string format

API vs GUI business rules

The CostGuard Client and Ticket GUIs enforce additional business logic and required fields that the create and modify endpoints do not.

For example, the GUI requires that Status and Title be supplied when creating a ticket, but the API submission will go through using the minimum properties from the above examples.

The All-powerful Delete

There are currently no restrictions in the APIs for ticket deletion—even closed tickets can be deleted with the web service user.

Setting and Modifying Journal Item Attributes

If you have an attribute definition associated with your journal type you can use the Journal service’s ModifyExtendedInformation operation to set the key/value pairs.

Code Sample Project

The sample project can be downloaded from the link below:
Getting Started with IDI Web Services Sample Project