Documenting BAQs

Kinetic ERP
, ,
21

In theory, I have a GitHub repository for exports of all of our customizations. In practice, I’m the only one who knows more about it than “it exists” and I haven’t updated it in ages.

More recently I’ve been documenting everything in a Word document. The BAQ section is 6 pages long—we don’t really have a lot that are shared and I chose to only document shared BAQs unless there was something noteworthy about a non-shared BAQ.

Even have a subsection for the ones I’ve borrowed from helpful EpiUsers :slight_smile:

image
image667×510 15.6 KB

4 Likes
22

Dependencies are a problem that version control doesn’t solve. Auditing consumers of BAQ’s is an almighty pain. Will modifying this BAQ break a spreadsheet I didn’t think of? What’s going to break when this API key gets rotated?

There’s an unavoidable make-sure requirement to identify requirements and dependencies in a consistent way. Any time a BAQ consumer is created or modified, that needs to be consistently and verbosely noted at the BAQ.

4 Likes
23

I don’t really track BAQs individually.
I do use the Comments to add dates/notes about the purpose, quirks, and change history.

Primarily, I track solutions. A solution might consist of:

  • BAQ(s)
  • App studio app
  • App customization
  • Menu entry
    or
  • BAQ(s)
  • Report data definition
  • Report definition
  • Report style(s)
  • Menu entry
    etc.

Solutions are backed up with Solution Workbench and documented in a shared Google Drive doc, with revision history. I’ve thought about Github, but since no one else here would comprehend that, then if I leave they’d have no documentation.

It would be ideal to track all BAQs individually, but the ROI just doesn’t seem to be there.

1 Like
24

Solution Tracking is a good idea. I had used the solution workbench when they first released it. I guess it worked alright, it is just slow and clunky.

25

The one thing to watch out for with Solution Workbench is the dependency problem that John mentioned. If I ALWAYS build a new solution as I need it, then there shouldn’t be a problem. But if I share a Directive or BAQ between multiple solutions, then I may have a previous version in one .CAB file and overwrite a newer version from another .CAB.

IFF, I have a textual way to represent all of my code (directives, layers, customizations, functions, minimal APIs, etc.) then I at least have a shot of finding the BAQ in any customized component with a simple search.

2 Likes
26

Using an ‘Admin’ user for dashboard/report related BAQs is what we’ve done. That removes them from personal lists so they don’t get forgotten about, accidentally deleted in a ‘rage cleanup’. If a change needs to be done we can just ‘Change Author’ back to ourselves, make the edit, then change author back to admin and it’s back where it needs to be, keeping our personal collection alot cleaner.

Prefixes for multi company is a good idea and is what we’ve done too. I’m not so keen on the numbering but i’m sure there’s value in that depending on your company size.

2 Likes
27

We used to have a series of solutions which were stored in order of dependency, which worked ok. Not perfect, but ok.

Not being able to easily see inside solutions for their content, and even worse when they were installed, the only simple way to see that they were installed was to go and try and delete them… Less than ideal. I have not looked recently if that has changed.

2 Likes
28

Fair warning, I don’t have a professional bone in my body. :upside_down_face:

I have authored about 520 BAQs in the past ~3 years. A handful of them are useful. All created in 10.2.400, so none of them have comments. Aside from sticking to naming conventions, I created a dashboard to search them by different criteria.

There are several prefixes I use to determine if the BAQ is for production, for reference, a simple data request, or is a template for complex and reusable structures.

And lastly, I always include the Report ID and SSRS file location in the footer of every report so I can track things down later on.

4 Likes
29

I like this idea! I don’t have a dedicated admin account, just a me and one other person that are Security Managers. Do you have an account named something like “admin” with security manager permissions? This seems like it should be the proper way to do BAQs you need for daily company work. IDK why we haven’t done that yet. :thinking:

30

Some DevOps teams (no Epicor users that I’m aware of) have deployment accounts. Nobody but that one deployment account can push to production. The deployment system keeps track of the changes. It’s a nice model for those with SOX requirements.

2 Likes
31

Seems to fit well with POLP.

1 Like
32

Yes. we have a UserID ‘Admin’, security manager permissions, etc. I’m not sure the user would even need much permissions as it’s just a holding ground for BAQ’s, it’s not like that user is ever logged into to create a BAQ’s or dashboards etc, we just take control of the BAQ when we need to update, and change it back when we’re done.

1 Like
33

I am using an external project management software for all documentation, requirements, attachments and so on (Atlassian Jira). The BAQ ID is exactly the Jira ID so I know where to go for all the related documentation. Of course instead of Jira ID you can use the ID from your internal support ticketing system and of course, use also the comments Tab in the BAQ. This way when it needs updates I can get back to the original request and see what was requested 2 years ago.

1 Like
34

I have been using Smartsheet to track requests and note BAQs and others
It allows attachments so I will export BAQs

I have created a BAQ on the query table. One field holds the logic so you can search for a query that is using a particular table or function
This BAQ was updated on the latest version 2024.2.12

XS_BoB.baq (13.0 KB)

1 Like
35

Don’t forget you can do some BPMs to track who executes each BAQ and when (to a UD table). I use this to determine unused BAQs which I then export and remove from the system.

Combined with naming conventions we can keep our list cleaned up.

We’re about to move to 2024.2 and I plan on using the comment field.

5 Likes
36

Doug,
Would you be able to share details on that BPM? It seems like a fantastic way to see who’s using what. We’re in the middle of our migration to Kinetic (from the Classic UI), and managers often ask ‘Who’s running this dashboard’ when I show them the activity log. Thanks!

2 Likes
37

It’s a preprocessor method directive on the Ice.BO.DynamicQuery Execute method:

image
image1024×211 36.9 KB

The first BO Method above are getting a new record from the UD table (in my case UD20). The last BO Method is the update.

This is my code block:

var row = dsUD20.UD20.First();

row.Company = callContextClient.CurrentCompany;

row.Key1 = queryDS.DynamicQuery.First().QueryID;
row.Key2 = DateTime.Today.ToString("yyyy-MM-dd");
row.Key3 = DateTime.Now.ToString("HH:mm:ss");
row.Key4 = callContextClient.CurrentUserId;
row.Key5 = Guid.NewGuid().ToString();

row.CheckBox01 = queryDS.DynamicQuery.First().SystemFlag;

row.ShortChar01 = "Execute";
row.ShortChar02 = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss.fffffff");

if (callContextClient.AssemblyName == null)
{
  row.Character01 = "BAQDesigner";
}
else if (callContextClient.AssemblyName == string.Empty)
{
  row.Character01 = "REST";
}
else 
  row.Character01 = callContextClient.AssemblyName;
row.RowMod = "A";

You can change anything you want…

I have one for ExecuteByID as well. It’s in a strange place and I have to go back through my notes. It’s the same setup except you change these lines from:

row.CheckBox01 = queryDS.DynamicQuery.First().SystemFlag;
row.ShortChar01 = "Execute";

to

row.CheckBox01 = Db.QueryHdr.Where(q=>q.QueryID==queryID).Select(q=>(bool?)q.SystemFlag).FirstOrDefault() ?? true
row.ShortChar01 = "ExecuteByID";
6 Likes