How Custom Functions are converted

This page describes how TrialGrid converts a C# Custom Function from the V1 to the V2 Medidata Rave API, for those who want to know what the 'Convert to V2' button and the "Convert to V2 API" action change, and why a function may not convert. Converting to the V2 API describes how to start a conversion, and how conversions are licensed.

The approach

TrialGrid makes only the changes V2 needs, and leaves everything else in the Source Code as it was, including its layout and comments.

  1. Rave says what to change. TrialGrid validates the Source Code with Medidata Designer. For each V1 reference, Medidata Rave reports the line and column it is on, the V1 type or member, and usually the V2 replacement. Medidata Rave has compiled the code, so it knows the type of every object, which the Source Code alone often doesn't show.

  2. |appname| makes the change. Where V2 keeps the same shape, the change is the name Medidata Rave suggests. Where the shape changes, for example an argument moves or a method becomes a property, a rule below makes it.

  3. Rave checks the result. The converted Source Code is validated again. Medidata Rave reports some V1 references only once those around them have changed, so if any remain the conversion is repeated, up to five times. A compile error from an ID that V2 gives as a reference, rather than a number, is repaired the same way: see below.

  4. The result is checked before it is saved. It must compile with no errors and no API Compatibility warnings, TrialGrid's own analysis must find no V1 left, and the function must use the same strings, call the same Custom Functions and perform the same actions as before. The arguments of each query, comment and sticky action are compared too.

If any step fails, the function is left unchanged and flagged with the reason. A function too long for Medidata Rave once converted is saved all the same, flagged for a person to shorten: see What isn't converted.

Functions that call each other

Custom Functions linked by PerformCustomFunction, as caller or callee, directly or through others, are converted as a group. A function that calls another by a name worked out when the code runs is treated as linked to every function its strings name.

A V2 function can call a V1 one, so a function that can't be converted doesn't stop the rest of its group. It stays V1, and so do the functions it calls, and the functions they call in turn, so that none of them returns a V2 list to a V1 function. A V2 list can't stand in for a V1 collection such as DataPoints. A function that calls one staying V1 is converted, unless it may pass that function a list. Only a literal, a calculation, the text from a string method such as ToString(), or a variable declared as a type that can't hold a list, is taken not to be one. A variable declared var or object, or a value read from another object, may be a list. A function that casts what one staying V1 returns to a list is held back too, whether it casts the call itself or a variable it keeps the result in. A V1 function's DataPoints can be read as an IReadOnlyList<IDataPoint>, but no other V1 list has been shown to be a V2 one. Each function held back this way is flagged with the name of the function that held it.

A group is saved only if none of its functions changed while it was being converted, including those that stay V1, since they decide which functions are held back.

A call keeps its arguments: CustomFunction.PerformCustomFunction(name, version, args) becomes Rave.PerformCustomFunction(name, version, args), and the called function reads its arguments as before.

Names and types

  • Types. Medidata Rave reports a V1 type once, so every use of it is changed: declarations, casts, generic arguments, arrays, typeof, as and is. A V1 type Medidata Rave doesn't report at all, as it may not in a cast, is changed to what Medidata Rave has suggested for it in other functions. A type written with its namespace, such as Medidata.Utilities.KeyValueCollection, is replaced whole. V1 types from Medidata.Core.Objects, Medidata.Utilities and other Medidata namespaces are all recognised.

  • The running check. ActionFunctionParams afp = (ActionFunctionParams)ThisObject; becomes IActionFunctionParams afp = Rave.Context.ActionFunctionParams;, and a member read through it, such as the action data point, becomes the matching Rave.Context property.

  • Renamed members take their V2 name, for example DataPoints on a record becomes AllDataPoints and FindByFieldOID becomes FindByFieldOid.

  • Static helpers moving to Rave, such as Number.IsValidInteger, become their Rave.* form with the same arguments.

  • Methods that become properties, such as dp.StandardValue(), lose their brackets.

  • IDs become references. x.ID becomes x.Ref where Medidata Rave suggests it, but only where the ID is just passed on, so that a reference serves as the number did: to a call whose V2 form takes a reference, to one of the function's own methods, into a variable that is itself only passed on, or compared for equality with another ID. A number declared from one, such as int v = subject.CRFVersionID;, is declared with var so it can hold the reference, and a variable, field, parameter or method's result declared int that carries one is declared as the reference type, which Medidata Rave names when it compiles the converted code.

  • IDs meaning no object. An ID compared with 0, meaning "no object", such as dp.Variable.DataDictionaryID > 0, becomes its reference compared with the reference type's default, dp.Variable.DataDictionaryRef != default(DataDictionaryRef). That default is what V2 gives when there is no object, as 0 is in V1. Other numbers, such as -1, are flagged: some IDs have them as real values, so they don't mean "no object". A variable carrying a reference that is given 0 is given the default instead, and so is the 0 in subject != null ? subject.CRFVersionID : 0. An ID compared with null is still compared with null. That comparison always gave the same answer, since neither a number nor a reference can be null.

  • A field's CRF version. V1 code often reads it as dp.Field.CRFVersion.ID. Medidata Rave says that ID, a library version's, has no V2 equivalent, but it is the field's CRFVersionID, so it becomes dp.Field.CrfVersionRef and is converted as any other ID.

  • IDs used any other way. A function that does anything else with the ID is flagged. Examples are adding it to text, calling ToString() on it and reading the result, storing or passing it as an object, or returning it as the function's result. A reference has no number, and its text isn't the old number.

  • Members reached through ?.. Medidata Rave gives no API Compatibility warning for a V1 member read with ?., only a compile error once the code around it is V2. Where V2 has the member under another capitalisation, as FindByFolderOID is FindByFolderOid, it is renamed on the line the error gives.

  • Documented replacements. Where Medidata documents a V2 replacement that Medidata Rave's warnings don't yet suggest, it is used: reading a user's Active becomes Enabled.

  • Freeze status. V2 has no freeze display status. dp.FreezeDisplayStatus == FreezeDisplayStatusEnum.Frozen becomes dp.IsFrozenRaw, and comparing with Unfrozen, or with !=, becomes !dp.IsFrozenRaw. V2's LockStatus isn't used: a data point frozen and then locked is still frozen to V1, and its LockStatus is Locked. Any other use of the V1 values, or of FreezeDisplayStatus itself, such as comparing it with a number or using it as text, is flagged.

Calls whose arguments change

  • Arguments follow their names. Where the V2 method takes the same arguments in a different order, they are matched by name, so CustomFunction.PerformQueryAction(text, group, ..., dp, ...) becomes Rave.Marking.PerformQueryAction(dp, text, group, ...). Where the names differ but the number is the same, they keep their positions.

  • A static call that becomes a method of its argument. CustomFunction.FetchAllDataPointsForOIDPath(field, form, folder, subject) becomes subject.GetDataPointsByOidPath(field, form, folder). V2 returns inactive data points too, so where V1 passed activeOnly as true the result is filtered to the active ones; false is simply dropped.

  • One method of several. Audits.Load(x) becomes x.FetchAudits(), the method Medidata Rave names on whichever type x is.

  • Lookups by coded data. V2's list of dictionary entries has no FindByCodedData, and V1's ignores case, so entries.FindByCodedData(code) becomes entries.FirstOrDefault(entry => string.Equals(entry.CodedData, code, StringComparison.OrdinalIgnoreCase)). The lookup works the code out again for each entry, so a code that changes something or calls a method other than a string method's, such as prefix + ++i, is flagged.

  • A page's container. V1's page.Parent is the page's folder, or its subject for a page at the subject's level. V2 gives every page a Subject, and only a page in a folder an Instance, so page.Parent is Instance becomes page.Instance != null and page.Parent is Subject becomes page.Instance == null. Any other use of Parent is flagged.

  • Doing or undoing. A method taking a Boolean that V2 splits in two, such as dp.Freeze(true) and dp.Freeze(false), becomes dp.Freeze() or dp.UnFreeze(); likewise Lock and Unlock. A variable chooses between them when the code runs.

  • Arguments V1 left out. V2 allows dp.Verify(isVerified) only with all three of its arguments written, so it becomes dp.Verify(isVerified, false, false).

  • Arguments V2 doesn't need. V2 knows who is calling, so a V1 method's interaction argument is dropped: Users.LoadAllUsers(interaction) becomes Rave.Configuration.FetchAllUsers().

  • Arguments passed with out or ref. A variable passed as out or ref is declared with the type the V2 method's parameter has, which must match it exactly.

Creating objects

  • Data pages and folders. new DataPage(instance, form, matrix), and instance.AddCRF(form, matrix), become instance.AddDataPage(form), which adds the page to the instance itself. Likewise new Instance(parent, folder, matrix) becomes parent.AddInstance(folder). The subject's V1 overloads add to the container they are given: subject.AddCRF(parent, form, matrix) becomes parent.AddDataPage(form), and subject.AddInstance(parent, folder, matrix) becomes parent.AddInstance(folder). The V1 DataPages.Add(page) or Instances.Add(instance) straight after is removed, since V2 has already added it, and so is one guarded only by if (page != null). V1's matrix isn't passed, since V2's AddDataPage(form) and AddInstance(folder) take none. V1 ignores the matrix it is given, placing the page or folder as V2's methods do, whether it is passed a subject matrix's ID, a matrix's, a folder's, a CRF version's or 0. The matrix is left out wherever reading it changes nothing. A function that works it out with a method call is flagged, since leaving it out would skip the call.

  • Key value pairs. list.Add(new KeyValue(key, value)) becomes list.Add(key, value). A variable that holds a pair only so it can be added goes: pair = new KeyValue(key, value); list.Add(pair); becomes list.Add(key, value);, and so does setting pair.Key and pair.Value on the lines before the Add. In the second form the pair must be created anew for each Add: V1 adds one pair whose values change as the same object each time, so the list ends up holding the last values more than once, and such a function is left for a person. V2 can't create a pair anywhere else. A pair kept in an ArrayList and only ever read back with ToString(), which gives its value, is replaced by the text: items.Add(new KeyValue(text, text)) becomes items.Add(text). This needs the key and the value to be the same, and every ArrayList in the function to stay in variables and methods declared ArrayList. A pair the function keeps for itself becomes .NET's KeyValuePair<string, string>, which has the same Key and Value: items.Add(new KeyValue(form, field)) and KeyValue pair = (KeyValue)item; become the same with KeyValuePair<string, string>. This needs every item read from an ArrayList to be cast back to a pair, and every pair to be read only for its Key and Value, since a KeyValuePair is never null and its text isn't V1's. Any other pair kept as an object is flagged.

  • Collections. A V1 collection, such as DataPoints, becomes a read-only list in V2, as V2's methods return, even where Medidata Rave suggests a List. Where the function adds to, removes from or sorts one, it is declared as a List instead, holding a copy of what it is given. Variables declared together all become List when any of them is changed. new DataPoints() becomes new List<IDataPoint>(). A V2 method returning a sequence rather than a list, such as FilterDataPagesByFormOid, has .ToList() added so its result can still be counted and indexed. A V1 collection was also an ICollection, which a V2 list isn't, so a V2 list passed where one is taken, as in new ArrayList(dps), is passed as a copy: new ArrayList(dps.ToList()). A data dictionary's EntriesCount becomes the Count of its Entries.

  • Factories. A V1 constructor that V2 replaces with a factory, such as new KeyValueCollection(), becomes the factory call, here Rave.Edc.CreateKeyValueCollection().

Statements

  • Setting Active. For a data point, record, data page or folder, V2 has no setter: x.Active = true; becomes x.Activate(null);, false becomes x.InActivate(null);, and a variable chooses between them when the code runs. Reading Active is unchanged.

  • The latest entered value. A common helper keeps a data point's entered values in a SortedList keyed by audit ID, so that the last is the latest. V2's audits have no ID, and Medidata advise ordering by creation time. The audits are therefore ordered newest first by AuditTime, and each is keyed by its place counted from the end, so the newest still sorts last. This needs the list to be only added to, counted and read by index, and the audits to be loaded once and walked by index from the start; otherwise the function is flagged.

  • Static helper methods. A function's own static helper methods could call V1's static methods, but they can't reach Rave. If any of them uses it after converting, none of the function's helper methods stays static.

What isn't converted

A function is flagged rather than converted when it uses:

  • something Medidata Rave says has no V2 equivalent, such as LibraryVersion.ID or setting a user's Active;

  • an endpoint Medidata Rave 2025.2.0 removed, or database access, which needs replacing with a stored procedure or another approach;

  • a V1 member or method whose V2 replacement has a different shape that no rule above covers;

  • subject.GetDataPointByFieldName(name). It finds the data points of every form with a field of that draft field name, where V2's GetDataPointsByField takes one field, found by its OID;

  • sorting a KeyValueCollection. V2's collection can't be sorted, read back or listed. V1's Sort() orders the pairs by value, ignoring case, so adding them in that order gives the same result.

It is also flagged, without converting, when its source is already longer than the 8,000 characters Medidata Rave takes.

V2's names are longer than V1's, so a function can go over the limit once converted. It is then laid out as the editor's Auto-indent button does, if that brings it under. If it is still too long, it is saved converted for a person to shorten, provided no V1 is left and it keeps its strings, calls and actions. Designer checks a copy without comments or layout when that fits. The flag is Too long if Designer found nothing in it, Too long, with problems if Designer found problems, which the flag lists, and Too long, unchecked if even the copy is too long to check. A Too long flag goes once the function fits, though only comments or layout were removed to make it fit. The others stay until the code itself changes, since the problems are still in it or it hasn't been checked.

The flag gives the reason, and its detail lists each reference with its line.

What has been checked in a study

The conversion targets the latest Medidata Rave, currently 2026.3.0, and converted code is checked against it. On an older Medidata Rave it can behave differently, so test converted Custom Functions on your own Medidata Rave before you use them. On 2026.1.0, for example, reading the DataDictionaryRef of a variable with no data dictionary throws an error, where the latest Medidata Rave gives the default. A function that compared DataDictionaryID with 0 to skip such variables, and was converted as described under "IDs meaning no object", then throws on exactly those variables. Rave.Architect.FetchFieldByOid likewise throws on 2026.1.0 for an OID that no field has, where the latest gives null.

Some rules can't be shown correct by compiling, so these have been checked on the latest Medidata Rave, by running a V1 and a V2 Custom Function side by side in a Medidata Rave study and comparing what each does:

  • AddDataPage(form) and AddInstance(folder) add the new page or folder where V1's constructors did, at the subject's level or inside a folder, and return it;

  • IsFrozenRaw gives the answer V1's freeze status comparison did for a data point that is frozen, unfrozen, locked, or frozen and then locked;

  • a page added to a folder is treated the same whichever subject matrix V1 passed: in a folder from a merged matrix, pages added with another object's subject matrix, with the folder's own and with V2's AddDataPage(form) all stay, active, when the matrix is unmerged;

  • GetDataPointsByOidPath returns what V1's FetchAllDataPointsForOIDPath did, inactive data points included, and filtering it to the active ones matches V1's activeOnly;

  • setting a record's Active and calling InActivate(null) or Activate(null) do the same, and an inactive record still holds its fields;

  • two references to the same data point are equal and two to different data points are not, as their IDs were;

  • Verify written with its two further arguments false verifies and unverifies a data point as V1's one-argument call does, including for a user whose role has no permission to verify: both verify the data point;

  • Freeze(), UnFreeze(), Lock() and Unlock() do what V1's Freeze and Lock did with true and false;

  • FetchAudits() returns the audits Audits.Load did, in the same order, newest first;

  • FilterDataPagesByFormOid(...).ToList() holds the pages V1's FilterDataPagesByFormOID did, in the same order;

  • a Custom Function called through Rave.PerformCustomFunction receives the arguments it was passed, as it did in V1;

  • a V2 Custom Function can call a V1 one, and read a DataPoints it returns as an IReadOnlyList<IDataPoint>, but a V2 list it passes isn't a V1 collection;

  • V1's AddCRF, AddInstance, new DataPage and new Instance place the new page or folder as AddDataPage(form) and AddInstance(folder) do, whether they are passed a subject matrix's ID, a matrix's, a folder's, a CRF version's or 0;

  • ordering a data point's audits newest first by AuditTime gives the order FetchAudits() does;

  • a field with no data dictionary has a DataDictionaryRef equal to default(DataDictionaryRef);

  • Rave.Configuration.FetchAllUsers() returns the users V1's Users.LoadAllUsers(interaction) did;

  • a field's CRFVersion.ID is its CRFVersionID, and finds the same variable as V2's CrfVersionRef;

  • a data dictionary's EntriesCount is the number of its Entries, as V2's Entries.Count is;

  • V1's KeyValueCollection.Sort() orders the pairs by value, ignoring case;

  • V1's FindByCodedData ignores case;

  • V1's page.Parent is an Instance for a page in a folder and the Subject for one at the subject's level, and V2's page.Instance is null only for the second;

  • V1's GetDataPointByFieldName matches the draft field name on every form, which V2's field found by OID doesn't;

  • a user's Enabled gives the same answer as V1's Active for an active user, and for an inactive one in Rave Classic, the only place an inactive user was compared;

  • a V1 KeyValue read with ToString() gives its value.

Converted Custom Functions should be tested like any other change before they are used in production.