Hi everyone, 

Those of you who are doing Handler modifications for customers, or yourselves.  What have you found to be the best/clearest way for you to document the setup (meaning the interconnectedness of the Handlers themselves).

I have been trying to do this both using Visio, or similar software.  And just plainly writing down the flow.  I am looking for some ideas, to make it easy for other technicians to troubleshoot my setups, if I am not available.  Even with my own documentation, I do sometimes get confused about which step initiates what, and where it is calling.

Also, if you inherit systems with customizations, that is not documented very well, how do you go about tracing through the Handlers to get an idea of what they do and how?

I have always wanted to create a system that makes it easy to troubleshoot and identify quickly how and which Handlers are linked, and what the customizations actually do.

I do my documentation inside each Handler what the step does and so forth, but it would be nice to have an accessible document to look up in.

I hope I made myself clear, and I am sure others here might also benefit to share and see some of the methods used for documentation :)
#Handlers

------------------------------
Egill Palsson
Advania AB
------------------------------

Egill,

Let me start out by saying I've been doing handler development for a very long time and can confidently say there is no "best" way to do this. Each approach has it's own strengths and weaknesses. Over the years I've been brought into a few different teams and looked at what worked well and not so well for each group. In the end here are the guidelines I follow around handler development. First let me start with a quick note, subroutines are your friends, some may say I go a little too crazy with subroutines but one of the easiest ways to document things is by breaking up the code into small logical blocks which are easier to follow. Here are some other "tips"

• Logically group your custom handlers by name. For instance if the IVR is called Customer Care every handler in the call flow would start with CCIVR_<Function>.
• The main entry point for all of my IVRs will have MainIVR after the Prefix mentioned above. for example CCIVR_MainIVR. I will also use _EntryPoint for things that are not IVRs. The helps people find the "front" of the customization.
• When publishing the handlers new categories will be created, in the example above all of the customer care handlers would be in the CCIVR category. This helps find the other subroutines when building code.
• Every subroutine will have documentation in the initiator. The first entry will be written yyyy-mm-dd <Engineer's initials>: Description of what the subroutine does. This doesn't need to be super in depth but enough detail to help the next person figure out if this is the part of the code they are interested in looking at.
• Every time the subroutine is changed another entry is added to the initiator notes with the date stamp and engineer's initials along with a note about the steps added and any other notes about what was changed. For example: "2020-02-04 MAT: Added steps 8-11 to add a decision and alternate routing on the attribute Delinquent. This is to support the new Delinquent caller initiative." 
• If a particular part of code is confusing or would be hard to figure out function I will add notes in the tool steps in use explaining what it is doing.
• For locations in the subroutine where the code ends abruptly I will add custom debugging steps using the label to explain why this is OK. For instance if it is common for a loop to not have data I would create the debug label "This is expected sometimes".
• If a subroutine is to be used in multiple locations I use a Util_ prefix. The reason for this is its much easier to find fully custom handlers if they don't start with Custom like the built in customization points.
• I will also create a Visio flow with high level subroutine flow to help with knowledge transfer. I find that trying to document the entire flow in visio becomes way too much and easily becomes out of date without a rigid change control process where the document is forced to be updated.
• Hungarian notation is very important, copy the scheme Genesys already uses in the system handlers.
• If I'm pulling values from external systems such as web services I will keep the variable the same name as the return from the external system. This makes troubleshooting returns from web services much easier.
• Set variables which could need to be changed with initial values so they are easier to find.
• If the value of the variable will change often create a structured parameter or IA table to allow the values to be changed without republishing the handler often.

There are probably more guidelines I have which I can't think of right now because of course I have never documented this because that would make way too much sense.

Thanks,

------------------------------
Mark Tatera
ConvergeOne

Opinions are my own and not the views of my employer. Any suggestions or programming changes I suggest come with no warranty and should be tried at your own risk. If my comment helped you or solved your problem please consider marking my comment as best answer.
------------------------------

Original Message:
Sent: 02-04-2020 07:05
From: Egill Palsson
Subject: How do you document your Handler setups?

Hi everyone,

Those of you who are doing Handler modifications for customers, or yourselves.  What have you found to be the best/clearest way for you to document the setup (meaning the interconnectedness of the Handlers themselves).

I have been trying to do this both using Visio, or similar software.  And just plainly writing down the flow.  I am looking for some ideas, to make it easy for other technicians to troubleshoot my setups, if I am not available.  Even with my own documentation, I do sometimes get confused about which step initiates what, and where it is calling.

Also, if you inherit systems with customizations, that is not documented very well, how do you go about tracing through the Handlers to get an idea of what they do and how?

I have always wanted to create a system that makes it easy to troubleshoot and identify quickly how and which Handlers are linked, and what the customizations actually do.

I do my documentation inside each Handler what the step does and so forth, but it would be nice to have an accessible document to look up in.

I hope I made myself clear, and I am sure others here might also benefit to share and see some of the methods used for documentation :)
#Handlers

------------------------------
Egill Palsson
Advania AB
------------------------------

Thanks a lot Mark! :) this very valuable information to keep track of a lot of Handlers.  Some of them I am already doing, but others I never thought of.

Much appreciated

------------------------------
Egill Palsson
Advania AB
------------------------------

Original Message:
Sent: 02-04-2020 13:03
From: Mark Tatera
Subject: How do you document your Handler setups?

Egill,

Let me start out by saying I've been doing handler development for a very long time and can confidently say there is no "best" way to do this. Each approach has it's own strengths and weaknesses. Over the years I've been brought into a few different teams and looked at what worked well and not so well for each group. In the end here are the guidelines I follow around handler development. First let me start with a quick note, subroutines are your friends, some may say I go a little too crazy with subroutines but one of the easiest ways to document things is by breaking up the code into small logical blocks which are easier to follow. Here are some other "tips"

• Logically group your custom handlers by name. For instance if the IVR is called Customer Care every handler in the call flow would start with CCIVR_<Function>.
• The main entry point for all of my IVRs will have MainIVR after the Prefix mentioned above. for example CCIVR_MainIVR. I will also use _EntryPoint for things that are not IVRs. The helps people find the "front" of the customization.
• When publishing the handlers new categories will be created, in the example above all of the customer care handlers would be in the CCIVR category. This helps find the other subroutines when building code.
• Every subroutine will have documentation in the initiator. The first entry will be written yyyy-mm-dd <Engineer's initials>: Description of what the subroutine does. This doesn't need to be super in depth but enough detail to help the next person figure out if this is the part of the code they are interested in looking at.
• Every time the subroutine is changed another entry is added to the initiator notes with the date stamp and engineer's initials along with a note about the steps added and any other notes about what was changed. For example: "2020-02-04 MAT: Added steps 8-11 to add a decision and alternate routing on the attribute Delinquent. This is to support the new Delinquent caller initiative." 
• If a particular part of code is confusing or would be hard to figure out function I will add notes in the tool steps in use explaining what it is doing.
• For locations in the subroutine where the code ends abruptly I will add custom debugging steps using the label to explain why this is OK. For instance if it is common for a loop to not have data I would create the debug label "This is expected sometimes".
• If a subroutine is to be used in multiple locations I use a Util_ prefix. The reason for this is its much easier to find fully custom handlers if they don't start with Custom like the built in customization points.
• I will also create a Visio flow with high level subroutine flow to help with knowledge transfer. I find that trying to document the entire flow in visio becomes way too much and easily becomes out of date without a rigid change control process where the document is forced to be updated.
• Hungarian notation is very important, copy the scheme Genesys already uses in the system handlers.
• If I'm pulling values from external systems such as web services I will keep the variable the same name as the return from the external system. This makes troubleshooting returns from web services much easier.
• Set variables which could need to be changed with initial values so they are easier to find.
• If the value of the variable will change often create a structured parameter or IA table to allow the values to be changed without republishing the handler often.

There are probably more guidelines I have which I can't think of right now because of course I have never documented this because that would make way too much sense.

Thanks,

------------------------------
Mark Tatera
ConvergeOne

Opinions are my own and not the views of my employer. Any suggestions or programming changes I suggest come with no warranty and should be tried at your own risk. If my comment helped you or solved your problem please consider marking my comment as best answer.

Original Message:
Sent: 02-04-2020 07:05
From: Egill Palsson
Subject: How do you document your Handler setups?

Hi everyone,

Those of you who are doing Handler modifications for customers, or yourselves.  What have you found to be the best/clearest way for you to document the setup (meaning the interconnectedness of the Handlers themselves).

I have been trying to do this both using Visio, or similar software.  And just plainly writing down the flow.  I am looking for some ideas, to make it easy for other technicians to troubleshoot my setups, if I am not available.  Even with my own documentation, I do sometimes get confused about which step initiates what, and where it is calling.

Also, if you inherit systems with customizations, that is not documented very well, how do you go about tracing through the Handlers to get an idea of what they do and how?

I have always wanted to create a system that makes it easy to troubleshoot and identify quickly how and which Handlers are linked, and what the customizations actually do.

I do my documentation inside each Handler what the step does and so forth, but it would be nice to have an accessible document to look up in.

I hope I made myself clear, and I am sure others here might also benefit to share and see some of the methods used for documentation :)
#Handlers

------------------------------
Egill Palsson
Advania AB
------------------------------

+1 to everything Mark said.  
as troubleshooting aids in my handlers I do these things:

• When setting attribute on the interaction, I name them with a prefix like MyIVR_[AttributeName].  This allows for the use of "Get Wildcard Attributes" to see current information.
• Set the IVR_EnterLevel as the interaction enters each level in the handlers.  You can query this in the IVRHistory table to trace a call through the IVR.
• Also set IVR_ExitIVR to track that.
• When setting these values, I also set an attribute on the interaction that Indicates the IVR level so that I can see that in real time with a custom column in ICBM.  

As far as undocumented handlers of unknown origin, good luck :).  A rudimentary method is to debug CustomSubroutineInitiatorRouter or other custom entry points to establish begin points for program flow.

------------------------------
Tim Cannon
------------------------------

Original Message:
Sent: 02-05-2020 02:49
From: Egill Palsson
Subject: How do you document your Handler setups?

Thanks a lot Mark! :) this very valuable information to keep track of a lot of Handlers.  Some of them I am already doing, but others I never thought of.

Much appreciated

------------------------------
Egill Palsson
Advania AB

Original Message:
Sent: 02-04-2020 13:03
From: Mark Tatera
Subject: How do you document your Handler setups?

Egill,

Let me start out by saying I've been doing handler development for a very long time and can confidently say there is no "best" way to do this. Each approach has it's own strengths and weaknesses. Over the years I've been brought into a few different teams and looked at what worked well and not so well for each group. In the end here are the guidelines I follow around handler development. First let me start with a quick note, subroutines are your friends, some may say I go a little too crazy with subroutines but one of the easiest ways to document things is by breaking up the code into small logical blocks which are easier to follow. Here are some other "tips"

• Logically group your custom handlers by name. For instance if the IVR is called Customer Care every handler in the call flow would start with CCIVR_<Function>.
• The main entry point for all of my IVRs will have MainIVR after the Prefix mentioned above. for example CCIVR_MainIVR. I will also use _EntryPoint for things that are not IVRs. The helps people find the "front" of the customization.
• When publishing the handlers new categories will be created, in the example above all of the customer care handlers would be in the CCIVR category. This helps find the other subroutines when building code.
• Every subroutine will have documentation in the initiator. The first entry will be written yyyy-mm-dd <Engineer's initials>: Description of what the subroutine does. This doesn't need to be super in depth but enough detail to help the next person figure out if this is the part of the code they are interested in looking at.
• Every time the subroutine is changed another entry is added to the initiator notes with the date stamp and engineer's initials along with a note about the steps added and any other notes about what was changed. For example: "2020-02-04 MAT: Added steps 8-11 to add a decision and alternate routing on the attribute Delinquent. This is to support the new Delinquent caller initiative." 
• If a particular part of code is confusing or would be hard to figure out function I will add notes in the tool steps in use explaining what it is doing.
• For locations in the subroutine where the code ends abruptly I will add custom debugging steps using the label to explain why this is OK. For instance if it is common for a loop to not have data I would create the debug label "This is expected sometimes".
• If a subroutine is to be used in multiple locations I use a Util_ prefix. The reason for this is its much easier to find fully custom handlers if they don't start with Custom like the built in customization points.
• I will also create a Visio flow with high level subroutine flow to help with knowledge transfer. I find that trying to document the entire flow in visio becomes way too much and easily becomes out of date without a rigid change control process where the document is forced to be updated.
• Hungarian notation is very important, copy the scheme Genesys already uses in the system handlers.
• If I'm pulling values from external systems such as web services I will keep the variable the same name as the return from the external system. This makes troubleshooting returns from web services much easier.
• Set variables which could need to be changed with initial values so they are easier to find.
• If the value of the variable will change often create a structured parameter or IA table to allow the values to be changed without republishing the handler often.

There are probably more guidelines I have which I can't think of right now because of course I have never documented this because that would make way too much sense.

Thanks,

------------------------------
Mark Tatera
ConvergeOne

Opinions are my own and not the views of my employer. Any suggestions or programming changes I suggest come with no warranty and should be tried at your own risk. If my comment helped you or solved your problem please consider marking my comment as best answer.

Original Message:
Sent: 02-04-2020 07:05
From: Egill Palsson
Subject: How do you document your Handler setups?

Hi everyone,

Those of you who are doing Handler modifications for customers, or yourselves.  What have you found to be the best/clearest way for you to document the setup (meaning the interconnectedness of the Handlers themselves).

I have been trying to do this both using Visio, or similar software.  And just plainly writing down the flow.  I am looking for some ideas, to make it easy for other technicians to troubleshoot my setups, if I am not available.  Even with my own documentation, I do sometimes get confused about which step initiates what, and where it is calling.

Also, if you inherit systems with customizations, that is not documented very well, how do you go about tracing through the Handlers to get an idea of what they do and how?

I have always wanted to create a system that makes it easy to troubleshoot and identify quickly how and which Handlers are linked, and what the customizations actually do.

I do my documentation inside each Handler what the step does and so forth, but it would be nice to have an accessible document to look up in.

I hope I made myself clear, and I am sure others here might also benefit to share and see some of the methods used for documentation :)
#Handlers

------------------------------
Egill Palsson
Advania AB
------------------------------

I would like to add to the excellent suggestions so far.

This advice pretty much comes from the Handler training, which I would advise you to take if you haven't already done so. You can assume that anyone who is customizing Handlers (or at least, those who attended the training!) will be aware of these, so it can provide some standardization between sites...

• Store any Handler that you have created and / or modified in the I3/IC/Handlers/Custom directory on the server. This way, you should (hopefully) not need to play "Hunt the Handler" when trying to figure out what changes have been made.
• Fill in the "Boiler Plate" text for all Handlers. This can be found by opening File->Properties for a handler, or when you publish it is the text at the "top". I always compare this to the comment block often seen at the start of a source file for text-based programming languages.
• Fill in all Labels and / or Notes on steps unless the step is so obvious that doing this would be insulting. Even then, remember that these fields do not affect the size or performance of the execultable Handler, so err on the side of over-documenting.
• If you use any kind of Ticketing System to manage your projects (E.G. JIRA) then make sure the ticket is referenced in the Handler's comments.
• Have a naming convention and stick to it (Both Mark and Tim offer some excelent suggestions on this)
• Remember the physical layout / size on screen of a Handler have no effect on the resulting Handler. Not really Documentation as much as readability, but don't bunch all your steps together, expand each step so all of it's Label etc. are showing and take the time to route the connections neatly (and NOT behind steps!!!)

If I think of anything else, I'll add it later.