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.
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.
|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.
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.
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,asandis. 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 asMedidata.Utilities.KeyValueCollection, is replaced whole. V1 types fromMedidata.Core.Objects,Medidata.Utilitiesand other Medidata namespaces are all recognised.The running check.
ActionFunctionParams afp = (ActionFunctionParams)ThisObject;becomesIActionFunctionParams afp = Rave.Context.ActionFunctionParams;, and a member read through it, such as the action data point, becomes the matchingRave.Contextproperty.Renamed members take their V2 name, for example
DataPointson a record becomesAllDataPointsandFindByFieldOIDbecomesFindByFieldOid.Static helpers moving to Rave, such as
Number.IsValidInteger, become theirRave.*form with the same arguments.Methods that become properties, such as
dp.StandardValue(), lose their brackets.IDs become references.
x.IDbecomesx.Refwhere 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 asint v = subject.CRFVersionID;, is declared withvarso it can hold the reference, and a variable, field, parameter or method's result declaredintthat 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 insubject != null ? subject.CRFVersionID : 0. An ID compared withnullis still compared withnull. 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'sCRFVersionID, so it becomesdp.Field.CrfVersionRefand 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, asFindByFolderOIDisFindByFolderOid, 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
ActivebecomesEnabled.Freeze status. V2 has no freeze display status.
dp.FreezeDisplayStatus == FreezeDisplayStatusEnum.Frozenbecomesdp.IsFrozenRaw, and comparing withUnfrozen, or with!=, becomes!dp.IsFrozenRaw. V2'sLockStatusisn't used: a data point frozen and then locked is still frozen to V1, and itsLockStatusisLocked. Any other use of the V1 values, or ofFreezeDisplayStatusitself, 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, ...)becomesRave.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)becomessubject.GetDataPointsByOidPath(field, form, folder). V2 returns inactive data points too, so where V1 passedactiveOnlyastruethe result is filtered to the active ones;falseis simply dropped.One method of several.
Audits.Load(x)becomesx.FetchAudits(), the method Medidata Rave names on whichever typexis.Lookups by coded data. V2's list of dictionary entries has no
FindByCodedData, and V1's ignores case, soentries.FindByCodedData(code)becomesentries.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 asprefix + ++i, is flagged.A page's container. V1's
page.Parentis the page's folder, or its subject for a page at the subject's level. V2 gives every page aSubject, and only a page in a folder anInstance, sopage.Parent is Instancebecomespage.Instance != nullandpage.Parent is Subjectbecomespage.Instance == null. Any other use ofParentis flagged.Doing or undoing. A method taking a Boolean that V2 splits in two, such as
dp.Freeze(true)anddp.Freeze(false), becomesdp.Freeze()ordp.UnFreeze(); likewiseLockandUnlock. 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 becomesdp.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)becomesRave.Configuration.FetchAllUsers().Arguments passed with out or ref. A variable passed as
outorrefis 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), andinstance.AddCRF(form, matrix), becomeinstance.AddDataPage(form), which adds the page to the instance itself. Likewisenew Instance(parent, folder, matrix)becomesparent.AddInstance(folder). The subject's V1 overloads add to the container they are given:subject.AddCRF(parent, form, matrix)becomesparent.AddDataPage(form), andsubject.AddInstance(parent, folder, matrix)becomesparent.AddInstance(folder). The V1DataPages.Add(page)orInstances.Add(instance)straight after is removed, since V2 has already added it, and so is one guarded only byif (page != null). V1's matrix isn't passed, since V2'sAddDataPage(form)andAddInstance(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))becomeslist.Add(key, value). A variable that holds a pair only so it can be added goes:pair = new KeyValue(key, value); list.Add(pair);becomeslist.Add(key, value);, and so does settingpair.Keyandpair.Valueon the lines before theAdd. In the second form the pair must be created anew for eachAdd: 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 anArrayListand only ever read back withToString(), which gives its value, is replaced by the text:items.Add(new KeyValue(text, text))becomesitems.Add(text). This needs the key and the value to be the same, and everyArrayListin the function to stay in variables and methods declaredArrayList. A pair the function keeps for itself becomes .NET'sKeyValuePair<string, string>, which has the sameKeyandValue:items.Add(new KeyValue(form, field))andKeyValue pair = (KeyValue)item;become the same withKeyValuePair<string, string>. This needs every item read from anArrayListto be cast back to a pair, and every pair to be read only for itsKeyandValue, since aKeyValuePairis 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 aList. Where the function adds to, removes from or sorts one, it is declared as aListinstead, holding a copy of what it is given. Variables declared together all becomeListwhen any of them is changed.new DataPoints()becomesnew List<IDataPoint>(). A V2 method returning a sequence rather than a list, such asFilterDataPagesByFormOid, has.ToList()added so its result can still be counted and indexed. A V1 collection was also anICollection, which a V2 list isn't, so a V2 list passed where one is taken, as innew ArrayList(dps), is passed as a copy:new ArrayList(dps.ToList()). A data dictionary'sEntriesCountbecomes theCountof itsEntries.Factories. A V1 constructor that V2 replaces with a factory, such as
new KeyValueCollection(), becomes the factory call, hereRave.Edc.CreateKeyValueCollection().
Statements
Setting Active. For a data point, record, data page or folder, V2 has no setter:
x.Active = true;becomesx.Activate(null);,falsebecomesx.InActivate(null);, and a variable chooses between them when the code runs. ReadingActiveis unchanged.The latest entered value. A common helper keeps a data point's entered values in a
SortedListkeyed 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 byAuditTime, 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.IDor setting a user'sActive;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'sGetDataPointsByFieldtakes one field, found by its OID;sorting a
KeyValueCollection. V2's collection can't be sorted, read back or listed. V1'sSort()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)andAddInstance(folder)add the new page or folder where V1's constructors did, at the subject's level or inside a folder, and return it;IsFrozenRawgives 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;GetDataPointsByOidPathreturns what V1'sFetchAllDataPointsForOIDPathdid, inactive data points included, and filtering it to the active ones matches V1'sactiveOnly;setting a record's
Activeand callingInActivate(null)orActivate(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;
Verifywritten with its two further argumentsfalseverifies 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()andUnlock()do what V1'sFreezeandLockdid withtrueandfalse;FetchAudits()returns the auditsAudits.Loaddid, in the same order, newest first;FilterDataPagesByFormOid(...).ToList()holds the pages V1'sFilterDataPagesByFormOIDdid, in the same order;a Custom Function called through
Rave.PerformCustomFunctionreceives the arguments it was passed, as it did in V1;a V2 Custom Function can call a V1 one, and read a
DataPointsit returns as anIReadOnlyList<IDataPoint>, but a V2 list it passes isn't a V1 collection;V1's
AddCRF,AddInstance,new DataPageandnew Instanceplace the new page or folder asAddDataPage(form)andAddInstance(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
AuditTimegives the orderFetchAudits()does;a field with no data dictionary has a
DataDictionaryRefequal todefault(DataDictionaryRef);Rave.Configuration.FetchAllUsers()returns the users V1'sUsers.LoadAllUsers(interaction)did;a field's
CRFVersion.IDis itsCRFVersionID, and finds the same variable as V2'sCrfVersionRef;a data dictionary's
EntriesCountis the number of itsEntries, as V2'sEntries.Countis;V1's
KeyValueCollection.Sort()orders the pairs by value, ignoring case;V1's
FindByCodedDataignores case;V1's
page.Parentis anInstancefor a page in a folder and theSubjectfor one at the subject's level, and V2'spage.Instanceis null only for the second;V1's
GetDataPointByFieldNamematches the draft field name on every form, which V2's field found by OID doesn't;a user's
Enabledgives the same answer as V1'sActivefor an active user, and for an inactive one in Rave Classic, the only place an inactive user was compared;a V1
KeyValueread withToString()gives its value.
Converted Custom Functions should be tested like any other change before they are used in production.